autotel-sentry

Convenience helpers for sending Autotel (OpenTelemetry) traces to Sentry via OTLP. The package parses a Sentry DSN into the OTLP endpoint and auth headers that Autotel's init() expects, and installs a global Sentry event processor that attaches the active OTel trace_id and span_id to every Sentry error event so errors and traces are linked in the Sentry UI.

Prerequisites

• Node.js 22+
• @sentry/node >= 10.47.0 (exposes getGlobalScope)
• autotel (peer dependency)

Installation

pnpm add autotel autotel-sentry @sentry/node

Quick start

import * as Sentry from '@sentry/node';
import { init, shutdown, trace } from 'autotel';
import { linkSentryErrors, sentryOtlpConfig } from 'autotel-sentry';

const config = sentryOtlpConfig(process.env.SENTRY_DSN!);

// 1. Initialize Sentry — tell it not to register its own OTel SDK
Sentry.init({ dsn: config.dsn, skipOpenTelemetrySetup: true });

// 2. Initialize Autotel — it owns OTel and exports traces to Sentry's OTLP endpoint
init({ service: 'my-app', endpoint: config.endpoint, headers: config.headers });

// 3. Link Sentry errors to the active OTel trace
linkSentryErrors(Sentry);

skipOpenTelemetrySetup: true is required because Sentry SDK v8+ registers its own OTel SDK internally. Autotel owns OTel setup; without this flag you get duplicate span processors and broken traces.

API reference

sentryOtlpConfig(dsn: string): SentryOtlpConfig

Parses a Sentry DSN and returns the three values needed to wire Autotel to Sentry's OTLP ingestion endpoint.

const config = sentryOtlpConfig('https://<key>@o<org>.ingest.sentry.io/<project>');
// config.dsn      — normalized DSN string (pass to Sentry.init)
// config.endpoint — OTLP base URL (pass to Autotel init as `endpoint`)
// config.headers  — auth headers (pass to Autotel init as `headers`)

Throws if the DSN is missing or cannot be parsed.

linkSentryErrors(sentry: SentryLinkable): void

Installs a global Sentry event processor that reads the active OTel span from @opentelemetry/api and merges trace_id and span_id into every outgoing Sentry event's contexts.trace. Call this once, after both Sentry.init() and init().

Type: SentryOtlpConfig

interface SentryOtlpConfig {
  dsn: string;                       // Normalized DSN for Sentry.init
  endpoint: string;                  // OTLP base endpoint (Autotel appends /v1/traces)
  headers: Record<string, string>;   // Auth headers for OTLP requests
}

Type: SentryLinkable

Minimal interface required by linkSentryErrors(). @sentry/node >= 10.47.0 satisfies it automatically.

interface SentryLinkable {
  getGlobalScope(): {
    addEventProcessor(fn: (event: Record<string, unknown>) => Record<string, unknown>): void;
  };
}

Migration from SpanProcessor approach

Earlier versions of this package used a SentrySpanProcessor / SentryPropagator bridge that relied on deprecated Sentry Hub APIs. That approach is removed.

Sentry SDK v8+ ships with its own OTel SDK internally. The recommended path is now to let Autotel own OTel and export traces directly to Sentry's OTLP endpoint — no custom span processor needed. Remove any references to createSentrySpanProcessor, SentrySpanProcessor, SentryPropagator, and instrumenter: 'otel' from your setup and replace them with the quick start above.

References

• Sentry OTLP Integration spec — protocol this package targets
• Sentry OTLP docs — Sentry-side OTLP configuration
• Autotel — init() and endpoint/headers options