@open-infra/telemetry-server

Node.js telemetry with one trace, log, and metric provider, bounded queues, privacy filtering, request context, and explicit shutdown. Uses official OpenTelemetry providers and OTLP/HTTP protobuf exporters.

Install

npm install @open-infra/telemetry-server

ESM only, with TypeScript declarations. Requires Node.js 20.11 or newer. Framework adapters are separate packages such as @open-infra/telemetry-express.

Start before importing the application

// instrumentation.mjs
import { createServerTelemetry } from '@open-infra/telemetry-server';

export const telemetry = createServerTelemetry({
  serviceName: 'orders-api',
  projectId: 'commerce',
  environment: 'production',
  exporter: {
    traceEndpoint: 'http://127.0.0.1:4318/v1/traces',
    logEndpoint: 'http://127.0.0.1:4318/v1/logs',
    metricEndpoint: 'http://127.0.0.1:4318/v1/metrics',
  },
});
await telemetry.start();

node --import ./instrumentation.mjs ./app.mjs

Import the same telemetry instance from application modules. Do not create a runtime per request. The default instrumentation patches Node HTTP; instrumentations: { auto: false } disables automatic instrumentation. auto: 'all' additionally requires the optional @opentelemetry/auto-instrumentations-node peer.

import { telemetry } from './instrumentation.mjs';

telemetry.logger.info('order.accepted', { 'order.channel': 'web' });
telemetry.telemetryMetrics.counter('orders.accepted', 1, { channel: 'web' });
const span = telemetry.tracer.startSpan('orders.process');
try {
  // Perform application work.
} finally {
  span.end();
}

startSpan does not make the span active. Use OpenTelemetry active-context APIs when child spans and correlated logs must share its context.

Shutdown and delivery

Stop accepting work, drain application requests, then call await telemetry.shutdown({ timeoutMs: 10000 }). Use forceFlush() for an explicit flush while running. installTelemetrySignalHandlers is available for signal-driven draining; it never calls process.exit().

Queues are memory-only and bounded. Crashes, saturation, and failed exports can lose data. Export success acknowledges the configured receiver, not final backend persistence. Deploy a durable Collector or Teleproxi spool when needed.

Configuration

• Server headers may contain receiver credentials; keep them out of browser bundles.
• Built-in exporter timeouts must fit their batch/metric-reader deadlines.
• policy controls redaction, URL/header capture, body allowlists, and metric dimensions.
• diagnostics.snapshot() reports queues, drops, export failures, and lifecycle state.
• Automatic resource detection uses environment, process, and host detectors; explicit resource configuration takes precedence.
• The /register preload reads the documented environment-variable subset. Calling createServerTelemetry uses explicit configuration and its defaults.

Operations · Logging

Apache-2.0.