@sophonz/node-sdk

한국어

Complete OpenTelemetry SDK for Node.js with automatic instrumentation, exception handling, and console capture.

Part of the Sophonz OpenTelemetry suite.

Install

bun add @sophonz/node-sdk
# or
pnpm add @sophonz/node-sdk
# or
npm install @sophonz/node-sdk

Usage

Programmatic Initialization

import { init, shutdown } from '@sophonz/node-sdk';

await init({
  service: 'my-app',
  apiKey: process.env.SOPHONZ_API_KEY,
  consoleCapture: true,
  experimentalExceptionCapture: true,
});

// Your application code here
console.log('Application running');

// Graceful shutdown
await shutdown();

Framework request enrichers

Spans for Express, Koa, Fastify, and NestJS are created automatically by the bundled auto-instrumentation. On top of that, the SDK ships per-framework request enrichers that copy baggage entries onto the active span, capture the client IP and user-agent, and forward them to the mutable trace context — so applications never need to import @opentelemetry/api directly.

// Express
import express from 'express';
import { sophonzExpressMiddleware } from '@sophonz/node-sdk';

const app = express();
app.use(sophonzExpressMiddleware());

// Koa
import Koa from 'koa';
import { sophonzKoaMiddleware } from '@sophonz/node-sdk';

const app = new Koa();
app.use(sophonzKoaMiddleware());

// Fastify
import Fastify from 'fastify';
import { sophonzFastifyPlugin } from '@sophonz/node-sdk';

const app = Fastify();
await app.register(sophonzFastifyPlugin());

// NestJS (works on both the Express and Fastify adapters)
import { NestFactory } from '@nestjs/core';
import { SophonzNestInterceptor } from '@sophonz/node-sdk';

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new SophonzNestInterceptor());

All four accept the same options:

• captureBaggage?: boolean - Copy baggage entries (prefixed baggage.). Default true.
• captureClientIp?: boolean - Capture http.client.ip. Default true.
• captureUserAgent?: boolean - Capture http.user_agent. Default true.
• attributes?: Attributes | ((req) => Attributes) - Extra static or per-request attributes.

Ordering note: the SDK must be initialized (init()) before the framework modules are loaded. The simplest pattern is to call init() at the top of your entrypoint and load the app via dynamic import() afterwards (see the sophonz-express-server / sophonz-fastify-server / sophonz-nestjs-server example apps).

Re-exported OpenTelemetry API

The OTel API surface is re-exported so you don't have to add @opentelemetry/api / @opentelemetry/api-logs as direct dependencies:

import { trace, context, propagation, metrics, logs } from '@sophonz/node-sdk';

const span = trace.getActiveSpan();

Debugging payloads

import { init, enableDebugPayloadExporters } from '@sophonz/node-sdk';

init({ service: 'my-app' });
if (process.env.SOPHONZ_DEBUG_PAYLOAD === 'true') {
  // Dump every exported span/log to the terminal alongside the OTLP exporter.
  void enableDebugPayloadExporters();
}

Command-line Instrumentation

Wrap your Node.js application with the preload binary:

node -r @sophonz/node-sdk/build/bin/opentelemetry-instrument.js app.js

Or use the provided CLI:

opentelemetry-instrument app.js

API

init(config?: Partial<SDKConfig>): Promise<void>

Initialize the SDK with automatic instrumentation enabled.

initSDK(config: SDKConfig): void

Initialize the SDK with explicit configuration control.

shutdown(): Promise<void>

Gracefully shut down the SDK and flush all telemetry.

setTraceAttributes(attributes: Attributes): void

Set global trace attributes on the mutable context.

sophonzExpressMiddleware(options?): RequestHandler

Express request middleware that enriches the active span and mutable trace context with baggage, client IP, and user-agent.

sophonzKoaMiddleware(options?): Middleware

Koa equivalent of sophonzExpressMiddleware.

sophonzFastifyPlugin(options?): FastifyPluginCallback

Fastify plugin (registers an onRequest hook) that performs the same enrichment. Register with app.register(sophonzFastifyPlugin()).

SophonzNestInterceptor / sophonzNestInterceptor(options?)

NestJS NestInterceptor that performs the same enrichment. Register with app.useGlobalInterceptors(new SophonzNestInterceptor()). Works on both the Express and Fastify platform adapters.

enableDebugPayloadExporters(): Promise<void>

Attach console exporters to the initialized providers to print every span and log record. Call after init/initSDK.

SDKConfig Options

• service?: string - Service name (default from env or auto-detected)
• apiKey?: string - API key for exporter authentication
• consoleCapture?: boolean - Instrument console API (default true)
• experimentalExceptionCapture?: boolean - Capture uncaught exceptions (default true)
• sentryIntegrationEnabled?: boolean - Enable Sentry integration (default true)
• advancedNetworkCapture?: boolean - Capture HTTP headers and bodies
• disableTracing?: boolean - Disable trace export
• disableLogs?: boolean - Disable log export
• disableMetrics?: boolean - Disable metric export
• disableStartupLogs?: boolean - Suppress initialization messages
• stopOnTerminationSignals?: boolean - Graceful shutdown on SIGTERM/SIGINT (default true)
• detectResources?: boolean - Auto-detect resource attributes (default true)
• enableInternalProfiling?: boolean - Profile instrumentation startup time
• betaMode?: boolean - Enable beta features, including the global trace-attribute context
• programmaticImports?: boolean - Skip auto-registering instrumentations; register them yourself
• errorLogCapture?: boolean - Emit an error log record for every span that ends with an ERROR status (default true)
• additionalInstrumentations?: InstrumentationBase[] - Custom instrumentations
• instrumentations?: InstrumentationConfigMap - Override auto-instrumentation config
• metricReader?: MetricReader - Custom metric reader

Error Logs

Every span that ends with an ERROR status also produces an error log record, so a failed request is queryable from the logs pipeline without a trace query.

The record carries the span's trace.id and span.id. Because that context is whatever propagated into the process, an error raised while handling a request from an instrumented browser lands on the same trace as the browser span that started it.

Attributes follow the shape @sophonz/instrumentation-browser-exception uses for its own error logs, so both ends of a trace match one filter:

| Attribute | Value | |-----------|-------| | app.span.type | error | | component | error | | error | true | | exception.type | Exception class, or Error | | exception.message | Message, truncated at 1024 chars | | exception.stacktrace | Stack, truncated at 4096 chars | | trace.id / span.id | The failing span's ids | | span.name | The failing operation |

The exception is read from the span's exception event — what span.recordException() records, and what every OTel instrumentation (http, express, fastify, nestjs, database drivers) emits on failure. When a span sets an error status without recording an event, the status message is used instead.

Disable with errorLogCapture: false or SOPHONZ_NODE_ERROR_LOG_CAPTURE=false. disableLogs: true also turns it off.

Included Instrumentations

• HTTP/HTTPS
• Console API
• Node.js exceptions
• Sentry integration
• Runtime metrics
• Express / Koa / Fastify / NestJS (auto-instrumentation + request enrichers)
• Express/Koa error handlers

Peer dependencies

• @opentelemetry/api
• @opentelemetry/sdk-node
• @opentelemetry/auto-instrumentations-node

Environment Variables

• SOPHONZ_API_KEY - API key for exporter
• OTEL_SERVICE_NAME - Service name
• OTEL_LOG_LEVEL - Diagnostics log level
• SOPHONZ_STARTUP_LOGS - Show/hide initialization messages
• SOPHONZ_NODE_ERROR_LOG_CAPTURE - Emit error logs for failed spans (default true)
• Additional OTEL_* variables for OpenTelemetry configuration

License

See LICENSE in this package.

Part of sophonz-js.