Atlas ID Observability

Production-focused observability utilities for Node.js services using OpenTelemetry. This package standardizes tracing, metrics, and logging initialization so services share consistent resource metadata and export behavior.

Install

pnpm add @atlas-id/observability

Usage

Single entrypoint

import {
  initializeObservability,
  startSpan,
  createCounter,
  logWithContext,
  shutdownObservability,
} from '@atlas-id/observability';

initializeObservability({
  serviceName: 'users-api',
  serviceVersion: '1.2.3',
  tracing: { enabled: true },
  metrics: { enabled: true },
  logging: { enabled: true },
  shutdownOnSignal: true,
});

const requestCounter = createCounter('http_requests_total', 'Total HTTP requests');

await startSpan('healthcheck', async (span) => {
  requestCounter.add(1, { route: '/health' });
  logWithContext('info', 'healthcheck ok', { spanId: span.spanContext().spanId });
});

await shutdownObservability();

Fine-grained initialization

import {
  initializeTracing,
  initializeMetrics,
  initializeLogging,
  shutdownTracing,
  shutdownMetrics,
  shutdownLogging,
} from '@atlas-id/observability';

initializeTracing({ serviceName: 'users-api' });
initializeMetrics({ serviceName: 'users-api' });
initializeLogging('users-api');

await shutdownTracing();
await shutdownMetrics();
shutdownLogging();

Configuration

Tracing (initializeTracing)

• serviceName (required)
• serviceVersion (optional, default 0.1.0 or SERVICE_VERSION)
• endpoint (optional; OTLP traces endpoint)
• enabled (optional)
• resourceAttributes (optional; extra OpenTelemetry resource attributes)
• instrumentations (optional; override auto-instrumentations)

Metrics (initializeMetrics)

• serviceName (required)
• serviceVersion (optional, default 0.1.0 or SERVICE_VERSION)
• endpoint (optional; OTLP metrics endpoint)
• exportIntervalMillis (optional, default 10000)
• enabled (optional)
• resourceAttributes (optional; extra OpenTelemetry resource attributes)

Logging (initializeLogging)

• serviceName (required)
• serviceVersion (optional, default 0.1.0 or SERVICE_VERSION)

Observability (initializeObservability)

• shutdownOnSignal (optional; auto-shutdown on SIGINT/SIGTERM)

Environment variables

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
• OTEL_EXPORTER_OTLP_ENDPOINT (base OTLP endpoint)
• LOG_LEVEL
• SERVICE_NAME (used by getLogger fallback)
• SERVICE_VERSION

API Notes

• startSpan accepts sync or async functions and always ends the span.
• logWithContext automatically attaches trace and span IDs from active context when available.
• createObservableGauge registers an async gauge callback.

Publish

pnpm install
pnpm build
npm publish --access public