@navitech/otel

OpenTelemetry for Node and Bun applications on Hosted. One import; configured entirely by the OTEL_* variables Hosted's deployer puts on every workload (Hosted-v2/docs/deploy.md#opentelemetry); does nothing when they are absent.

SvelteKit (adapter-node, on Node or Bun)

// src/instrumentation.server.ts
import '@navitech/otel/register';

and in svelte.config.js, kit.experimental: tracing: { server: true }, instrumentation: { server: true }; plus @opentelemetry/api as a direct dependency. adapter-node runs the file before the app. On Node the HTTP entry span is named after Kit's route (RouteFromFrameworkProcessor); on Bun Kit's own root span is the entry.

Remote functions have no route of their own (Kit says unknown), so a call is routed remote:<name> — POST remote:saveCampaign. Kit's span for the call the collector names by type and function (query getMetrics).

Drizzle over libSQL is otherwise just an HTTP POST to sqld. Wrap the client and every statement is a span named SELECT campaigns, with the SQL in db.query.text:

import { tracedLibsql } from '@navitech/otel';
export const db = drizzle(tracedLibsql(createClient({ url, authToken })), { schema });

Node (NestJS, Fastify, anything on Node)

CMD ["node", "--import", "@navitech/otel/register", "build/index.js"]

Every supported library is instrumented — http, fetch/undici, fastify, express, NestJS, ioredis, bull, pg, pino (whose records are then sent over OTLP, linked to their trace — winston and bunyan too) — for CommonJS and ESM. fs, dns and net are off by default (OTEL_NODE_DISABLED_INSTRUMENTATIONS).

Bun

import '@navitech/otel/register'; // first line of the entry point
import { traced, tracedFetch } from '@navitech/otel';

globalThis.fetch = tracedFetch(globalThis.fetch);
Bun.serve({ port: 8787, fetch: traced(app.fetch, (req) => routeOf(req)) });

Bun only partly supports the module hooks automatic instrumentation needs, so nothing is patched there: traced() makes a server span per request (and continues an incoming traceparent), tracedFetch() a client span per call.

Logs

From 0.3.0 logs go to Tracely over OTLP, like traces — nothing else reads stdout.

• console.*, Node and Bun. Every call is also one log record: the body is exactly what is printed (util.format of the arguments), severity from the method (debug/trace → DEBUG, log/info → INFO, warn → WARN, error → ERROR), an Error argument fills exception.type / exception.message / exception.stacktrace, linked to the active trace and span. A multi-line message is one record.

• NestJS's logger, on Node. Every new Logger(ctx) (Nest's ConsoleLogger): one record per message, attribute nest.context; logger.error(msg, stack) stays one record with exception.stacktrace; an object message's fields become attributes.

• log.* for fields you can filter on: the message is the body, each field an attribute (nested objects JSON-stringified, an Error field → exception.*). Printed once to stdout too.

  import { log } from '@navitech/otel';
  log.info('order created', { orderId, total });
  log.error('payment failed', { orderId, err });

Everything is still printed to stdout (kubectl logs works as before). OTEL_LOGS_EXPORTER=none turns the sending off. What is printed before register runs, or by the runtime as the process dies (an uncaught exception, an OOM kill), is not sent.

Helpers (both runtimes)

| | | | --- | --- | | withSpan(name, fn, attrs?) | a span around fn; a throw marks it failed | | traced(handler, route?) | server spans for a (Request) => Response handler | | tracedFetch(fetch) | client spans + traceparent on outgoing calls | | tracedLibsql(client) | a span per statement of a @libsql/client (and its transactions) | | log.debug/info/warn/error/fatal(message, fields?) | a log record with fields as attributes, also printed | | logContext() | { trace_id, span_id } of the active span — only for text you print with a logger the package does not capture |

All are safe without an SDK: the OpenTelemetry API is a no-op until one starts.

Behaviour worth knowing

• The ESM hook covers only instrumented modules (http, pg, pino, …). Hooking every module breaks ESM live bindings in the application — SvelteKit's $env/dynamic/private came through empty. register.test.ts checks a live binding survives.

• db.query.text is the SQL as sent: with placeholders when it comes from Drizzle, but a sql.raw() or a hand-built string carries its values. Cut at 4 kB.

• On Bun, fetch is wrapped (client spans, traceparent), keeping Bun-only options (unix, proxy, …); NAVITECH_OTEL_FETCH=off opts out. The resource says process.runtime.name=bun.

• Off without OTEL_EXPORTER_OTLP_ENDPOINT, or with OTEL_SDK_DISABLED=true.

• Never overrides a variable the environment already sets.

• SIGTERM: flushes (at most 5 s), then exits 143 — unless the application has its own SIGTERM handler, in which case the application decides.

• A failure to start is logged and ignored: telemetry is never why an application does not run.

Getting it into an application

bun add @navitech/otel     # from the application's package dir; a runtime dependency

It is on npm, public (publishConfig.access). The Dockerfile's runtime stage must install production dependencies — the register module is loaded by the production process.

Publishing

Bump version, then from this directory:

bun run test && npm publish

prepublishOnly rebuilds dist/, so what is published is what was tested.

Tests

bun run test — unit tests, the helpers against an in-memory exporter (including propagation across two real Bun servers), console / log.* / NestJS capture (logs.test.ts), and register.js in real Node processes (the SIGTERM rules, and log records sent to a fake OTLP endpoint).