autotel-sentry 0.1.0

package/src/helpers.ts

@@ -0,0 +1,256 @@
+/**
+ * Helpers for mapping OpenTelemetry spans to Sentry transactions/spans and context.
+ * Aligned with Sentry's OpenTelemetry integration spec.
+ */
+
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import {
+  SEMATTRS_HTTP_URL,
+  SEMATTRS_HTTP_STATUS_CODE,
+  SEMATTRS_RPC_GRPC_STATUS_CODE,
+  SEMATTRS_EXCEPTION_MESSAGE,
+  SEMATTRS_EXCEPTION_STACKTRACE,
+  SEMATTRS_EXCEPTION_TYPE,
+} from '@opentelemetry/semantic-conventions';
+
+/** Sentry span status strings per their spec (maps to gRPC-style codes). */
+export type SentrySpanStatus =
+  | 'ok'
+  | 'cancelled'
+  | 'unknown_error'
+  | 'invalid_argument'
+  | 'deadline_exceeded'
+  | 'not_found'
+  | 'already_exists'
+  | 'permission_denied'
+  | 'resource_exhausted'
+  | 'failed_precondition'
+  | 'aborted'
+  | 'out_of_range'
+  | 'unimplemented'
+  | 'internal_error'
+  | 'unavailable'
+  | 'data_loss'
+  | 'unauthenticated';
+
+export interface ParsedSpanDescription {
+  op: string;
+  description: string;
+}
+
+/** OTel timestamps are typically in nanoseconds (HrTime or number). */
+export function convertOtelTimeToSeconds(time: number | [number, number]): number {
+  if (Array.isArray(time)) {
+    return time[0] + time[1] / 1e9;
+  }
+  return time / 1e9;
+}
+
+const CANONICAL_HTTP_MAP: Record<string, SentrySpanStatus> = {
+  '400': 'failed_precondition',
+  '401': 'unauthenticated',
+  '403': 'permission_denied',
+  '404': 'not_found',
+  '409': 'aborted',
+  '429': 'resource_exhausted',
+  '499': 'cancelled',
+  '500': 'internal_error',
+  '501': 'unimplemented',
+  '503': 'unavailable',
+  '504': 'deadline_exceeded',
+};
+
+const CANONICAL_GRPC_MAP: Record<string, SentrySpanStatus> = {
+  '1': 'cancelled',
+  '2': 'unknown_error',
+  '3': 'invalid_argument',
+  '4': 'deadline_exceeded',
+  '5': 'not_found',
+  '6': 'already_exists',
+  '7': 'permission_denied',
+  '8': 'resource_exhausted',
+  '9': 'failed_precondition',
+  '10': 'aborted',
+  '11': 'out_of_range',
+  '12': 'unimplemented',
+  '13': 'internal_error',
+  '14': 'unavailable',
+  '15': 'data_loss',
+  '16': 'unauthenticated',
+};
+
+export function mapOtelStatus(otelSpan: ReadableSpan): SentrySpanStatus {
+  const { status, attributes } = otelSpan;
+  const code = status.code;
+
+  if (code !== undefined && (code < 0 || code > 2)) {
+    return 'unknown_error';
+  }
+
+  if (code === 0 || code === 1) {
+    return 'ok';
+  }
+
+  const httpCode = attributes[SEMATTRS_HTTP_STATUS_CODE];
+  const grpcCode = attributes[SEMATTRS_RPC_GRPC_STATUS_CODE];
+
+  if (typeof httpCode === 'string') {
+    const sentryStatus = CANONICAL_HTTP_MAP[httpCode];
+    if (sentryStatus) return sentryStatus;
+  }
+  if (typeof httpCode === 'number') {
+    const sentryStatus = CANONICAL_HTTP_MAP[String(httpCode)];
+    if (sentryStatus) return sentryStatus;
+  }
+
+  if (typeof grpcCode === 'string') {
+    const sentryStatus = CANONICAL_GRPC_MAP[grpcCode];
+    if (sentryStatus) return sentryStatus;
+  }
+
+  return 'unknown_error';
+}
+
+/** Derive Sentry op and description from OTel span name, kind, and attributes. */
+export function parseSpanDescription(otelSpan: ReadableSpan): ParsedSpanDescription {
+  const { name, kind, attributes } = otelSpan;
+  const description = name || 'unknown';
+
+  const spanKind = kind ?? 0;
+  const isHttp = spanKind === 2 || attributes['http.method'] != null;
+  const isDb =
+    attributes['db.system'] != null ||
+    attributes['db.operation'] != null ||
+    attributes['db.statement'] != null;
+
+  let op = 'default';
+  if (isHttp) {
+    op = 'http.client';
+    const method = attributes['http.method'];
+    const route = attributes['http.route'] ?? attributes['http.target'];
+    if (method && route) op = 'http.server';
+  } else if (isDb) {
+    op = 'db.query';
+  }
+
+  return { op, description };
+}
+
+export interface TraceData {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+}
+
+export function getTraceData(otelSpan: ReadableSpan): TraceData {
+  const ctx = otelSpan.spanContext();
+  return {
+    traceId: ctx.traceId,
+    spanId: ctx.spanId,
+    parentSpanId: otelSpan.parentSpanContext?.spanId,
+  };
+}
+
+/** Check if the span represents a request to Sentry (ingestion); such spans must not be sent to Sentry. */
+export function isSentryRequestSpan(
+  otelSpan: ReadableSpan,
+  getDsnHost: () => string | undefined,
+): boolean {
+  const httpUrl = otelSpan.attributes[SEMATTRS_HTTP_URL];
+  if (httpUrl == null) return false;
+  const url = typeof httpUrl === 'string' ? httpUrl : String(httpUrl);
+  const host = getDsnHost();
+  if (!host) return false;
+  return url.includes(host);
+}
+
+/** Attributes and resource for Sentry's otel context. */
+export function getOtelContextFromSpan(otelSpan: ReadableSpan): {
+  attributes: Record<string, unknown>;
+  resource: Record<string, unknown>;
+} {
+  const attributes: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(otelSpan.attributes)) {
+    attributes[k] = v;
+  }
+  const resource: Record<string, unknown> = {};
+  const res = otelSpan.resource;
+  if (res && res.attributes) {
+    for (const [k, v] of Object.entries(res.attributes)) {
+      resource[k] = v;
+    }
+  }
+  return { attributes, resource };
+}
+
+/** Update a Sentry span with OTel span data (status, op, description, data). */
+export function updateSpanWithOtelData(
+  sentrySpan: { setStatus: (s: { status?: string }) => void; setData: (k: string, v: unknown) => void; op?: string; description?: string },
+  otelSpan: ReadableSpan,
+): void {
+  const status = mapOtelStatus(otelSpan);
+  sentrySpan.setStatus({ status });
+  sentrySpan.setData('otel.kind', otelSpan.kind ?? 0);
+  for (const [key, value] of Object.entries(otelSpan.attributes)) {
+    sentrySpan.setData(key, value);
+  }
+  const { op, description } = parseSpanDescription(otelSpan);
+  sentrySpan.op = op;
+  sentrySpan.description = description;
+}
+
+/** Update a Sentry transaction with OTel span data. */
+export function updateTransactionWithOtelData(
+  transaction: { setStatus: (s: { status?: string }) => void; op?: string; name?: string },
+  otelSpan: ReadableSpan,
+): void {
+  const status = mapOtelStatus(otelSpan);
+  transaction.setStatus({ status });
+  const { op, description } = parseSpanDescription(otelSpan);
+  transaction.op = op;
+  transaction.name = description;
+}
+
+/** Set otel context on transaction and finish it. */
+export function finishTransactionWithContextFromOtelData(
+  transaction: {
+    setContext: (name: string, ctx: { attributes?: Record<string, unknown>; resource?: Record<string, unknown> }) => void;
+    finish: (endTime?: number) => void;
+  },
+  otelSpan: ReadableSpan,
+): void {
+  const { attributes, resource } = getOtelContextFromSpan(otelSpan);
+  transaction.setContext('otel', { attributes, resource });
+  transaction.finish(convertOtelTimeToSeconds(otelSpan.endTime));
+}
+
+/** Build synthetic Error from OTel exception event attributes and capture with Sentry. */
+export function generateSentryErrorsFromOtelSpan(
+  otelSpan: ReadableSpan,
+  captureException: (error: Error, options?: { contexts?: Record<string, unknown> }) => void,
+): void {
+  const events = otelSpan.events ?? [];
+  for (const event of events) {
+    if (event.name !== 'exception') continue;
+    const attrs = event.attributes ?? {};
+    const message = (attrs[SEMATTRS_EXCEPTION_MESSAGE] as string) ?? 'Unknown error';
+    const stack = (attrs[SEMATTRS_EXCEPTION_STACKTRACE] as string) ?? '';
+    const type = (attrs[SEMATTRS_EXCEPTION_TYPE] as string) ?? 'Error';
+
+    const synthetic = new Error(message);
+    synthetic.name = type;
+    if (stack) synthetic.stack = stack;
+
+    const { attributes, resource } = getOtelContextFromSpan(otelSpan);
+    captureException(synthetic, {
+      contexts: {
+        otel: { attributes, resource },
+        trace: {
+          trace_id: otelSpan.spanContext().traceId,
+          span_id: otelSpan.spanContext().spanId,
+          parent_span_id: otelSpan.parentSpanContext?.spanId,
+        },
+      },
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * autotel-sentry: Bridge OpenTelemetry (Autotel) traces to Sentry.
+ */
+export { SentrySpanProcessor, createSentrySpanProcessor } from './processor';
+export type { SentryLike } from './processor';
+export { SentryPropagator, SENTRY_PROPAGATION_KEY } from './propagator';
+export type { SentryPropagationData } from './propagator';

package/src/processor.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SentrySpanProcessor, createSentrySpanProcessor } from './processor';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Span } from '@opentelemetry/sdk-trace-base';
+import { context } from '@opentelemetry/api';
+
+function createMockReadableSpan(overrides: Partial<{
+  name: string;
+  spanId: string;
+  traceId: string;
+  parentSpanId: string;
+  attributes: Record<string, unknown>;
+  resource: { attributes: Record<string, unknown> };
+  events: Array<{ name: string; attributes?: Record<string, unknown> }>;
+  status: { code: number };
+  kind: number;
+  startTime: [number, number];
+  endTime: [number, number];
+}> = {}): ReadableSpan {
+  return {
+    name: 'test-span',
+    kind: 0,
+    spanContext: () => ({
+      traceId: overrides.traceId ?? 'trace123',
+      spanId: overrides.spanId ?? 'span456',
+      traceFlags: 1,
+    }),
+    parentSpanContext: overrides.parentSpanId
+      ? { traceId: 'trace123', spanId: overrides.parentSpanId, traceFlags: 1 }
+      : undefined,
+    startTime: overrides.startTime ?? [0, 0],
+    endTime: overrides.endTime ?? [1, 0],
+    status: { code: overrides.status?.code ?? 1 },
+    attributes: overrides.attributes ?? {},
+    resource: overrides.resource ?? { attributes: { 'service.name': 'test' } },
+    events: overrides.events ?? [],
+    links: [],
+    duration: [1, 0],
+    ended: true,
+    instrumentationScope: { name: 'test', version: '1.0' },
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 0,
+  } as unknown as ReadableSpan;
+}
+
+function createMockSpan(overrides: Partial<{ name: string; spanId: string; parentSpanId: string }> = {}): Span {
+  const spanContext = () => ({
+    traceId: 'trace123',
+    spanId: overrides.spanId ?? 'span456',
+    traceFlags: 1,
+  });
+  return {
+    name: overrides.name ?? 'test-span',
+    spanContext,
+    parentSpanContext: overrides.parentSpanId
+      ? { traceId: 'trace123', spanId: overrides.parentSpanId, traceFlags: 1 }
+      : undefined,
+    startTime: [0, 0],
+  } as unknown as Span;
+}
+
+describe('SentrySpanProcessor', () => {
+  let mockSentry: {
+    getCurrentHub: ReturnType<typeof vi.fn>;
+    addGlobalEventProcessor: ReturnType<typeof vi.fn>;
+    captureException: ReturnType<typeof vi.fn>;
+  };
+  let mockHub: {
+    startTransaction: ReturnType<typeof vi.fn>;
+    getSpan: ReturnType<typeof vi.fn>;
+  };
+  let mockTransaction: {
+    startChild: ReturnType<typeof vi.fn>;
+    setStatus: ReturnType<typeof vi.fn>;
+    setContext: ReturnType<typeof vi.fn>;
+    finish: ReturnType<typeof vi.fn>;
+  };
+  let mockChildSpan: {
+    setStatus: ReturnType<typeof vi.fn>;
+    setData: ReturnType<typeof vi.fn>;
+    finish: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    mockTransaction = {
+      startChild: vi.fn(),
+      setStatus: vi.fn(),
+      setContext: vi.fn(),
+      finish: vi.fn(),
+    };
+    mockChildSpan = {
+      setStatus: vi.fn(),
+      setData: vi.fn(),
+      finish: vi.fn(),
+    };
+    mockHub = {
+      startTransaction: vi.fn(() => mockTransaction),
+      getSpan: vi.fn(),
+    };
+    mockSentry = {
+      getCurrentHub: vi.fn(() => mockHub),
+      addGlobalEventProcessor: vi.fn(),
+      captureException: vi.fn(),
+    };
+  });
+
+  it('registers a global event processor in constructor', () => {
+    new SentrySpanProcessor(mockSentry as any);
+    expect(mockSentry.addGlobalEventProcessor).toHaveBeenCalledTimes(1);
+    expect(typeof mockSentry.addGlobalEventProcessor.mock.calls[0][0]).toBe('function');
+  });
+
+  it('onStart creates a transaction when no parent', () => {
+    const processor = new SentrySpanProcessor(mockSentry as any);
+    const span = createMockSpan({ spanId: 'root' });
+    processor.onStart(span, context.active());
+    expect(mockHub.startTransaction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'test-span',
+        traceId: 'trace123',
+        spanId: 'root',
+        instrumenter: 'otel',
+      }),
+    );
+  });
+
+  it('onStart creates a child span when parent exists in map', () => {
+    const processor = new SentrySpanProcessor(mockSentry as any);
+    const parentSpan = createMockSpan({ spanId: 'parent' });
+    const childSpan = createMockSpan({ spanId: 'child', parentSpanId: 'parent' });
+    processor.onStart(parentSpan, context.active());
+    mockHub.startTransaction.mockReturnValue(mockTransaction);
+    processor.onStart(childSpan, context.active());
+    expect(mockTransaction.startChild).toHaveBeenCalledWith(
+      expect.objectContaining({
+        description: 'test-span',
+        spanId: 'child',
+        instrumenter: 'otel',
+      }),
+    );
+  });
+
+  it('onEnd updates and finishes transaction', () => {
+    const processor = new SentrySpanProcessor(mockSentry as any);
+    const span = createMockSpan({ spanId: 'root' });
+    processor.onStart(span, context.active());
+    const readableSpan = createMockReadableSpan({ spanId: 'root', traceId: 'trace123' });
+    (readableSpan as any).spanContext = () => ({ traceId: 'trace123', spanId: 'root' });
+    processor.onEnd(readableSpan);
+    expect(mockTransaction.setStatus).toHaveBeenCalled();
+    expect(mockTransaction.setContext).toHaveBeenCalledWith('otel', expect.any(Object));
+    expect(mockTransaction.finish).toHaveBeenCalled();
+  });
+
+  it('onEnd updates and finishes child span', () => {
+    const processor = new SentrySpanProcessor(mockSentry as any);
+    const parentSpan = createMockSpan({ spanId: 'parent' });
+    const childSpan = createMockSpan({ spanId: 'child', parentSpanId: 'parent' });
+    processor.onStart(parentSpan, context.active());
+    mockTransaction.startChild.mockReturnValue(mockChildSpan);
+    processor.onStart(childSpan, context.active());
+    const readableChild = createMockReadableSpan({
+      spanId: 'child',
+      parentSpanId: 'parent',
+    });
+    (readableChild as any).spanContext = () => ({ traceId: 'trace123', spanId: 'child' });
+    processor.onEnd(readableChild);
+    expect(mockChildSpan.setStatus).toHaveBeenCalled();
+    expect(mockChildSpan.finish).toHaveBeenCalled();
+  });
+
+  it('onEnd skips finishing when span is Sentry request', () => {
+    const processor = new SentrySpanProcessor(mockSentry as any);
+    const span = createMockSpan({ spanId: 'root' });
+    processor.onStart(span, context.active());
+    const readableSpan = createMockReadableSpan({
+      spanId: 'root',
+      attributes: { 'http.url': 'https://sentry.io/api/123/envelope/' },
+    });
+    (readableSpan as any).spanContext = () => ({ traceId: 'trace123', spanId: 'root' });
+    const hubWithDsn = {
+      ...mockHub,
+      getClient: () => ({ getDsn: () => ({ host: 'sentry.io' }) }),
+    };
+    mockSentry.getCurrentHub.mockReturnValue(hubWithDsn);
+    processor.onEnd(readableSpan);
+    expect(mockTransaction.finish).not.toHaveBeenCalled();
+  });
+
+  it('createSentrySpanProcessor returns a SentrySpanProcessor instance', () => {
+    const processor = createSentrySpanProcessor(mockSentry as any);
+    expect(processor).toBeInstanceOf(SentrySpanProcessor);
+  });
+});

package/src/processor.ts

@@ -0,0 +1,191 @@
+/**
+ * SentrySpanProcessor: converts OpenTelemetry spans to Sentry transactions/spans.
+ * Register with init({ spanProcessors: [new SentrySpanProcessor(Sentry)] }).
+ */
+
+import { trace } from '@opentelemetry/api';
+import type { Context } from '@opentelemetry/api';
+import type { Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import {
+  convertOtelTimeToSeconds,
+  getTraceData,
+  isSentryRequestSpan,
+  updateSpanWithOtelData,
+  updateTransactionWithOtelData,
+  finishTransactionWithContextFromOtelData,
+  generateSentryErrorsFromOtelSpan,
+} from './helpers';
+
+/** Minimal Sentry hub interface for creating transactions and spans. */
+export interface SentryHubLike {
+  startTransaction(ctx: SentryTransactionContextLike): SentryTransactionLike | undefined;
+  getSpan(): SentrySpanLike | undefined;
+}
+
+/** Context passed to startTransaction. */
+export interface SentryTransactionContextLike {
+  name: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  startTimestamp?: number;
+  instrumenter?: string;
+}
+
+/** Sentry transaction (root span). */
+export interface SentryTransactionLike {
+  startChild(ctx: SentrySpanContextLike): SentrySpanLike;
+  setStatus(s: { status?: string }): void;
+  setContext(name: string, ctx: Record<string, unknown>): void;
+  finish(endTime?: number): void;
+  name?: string;
+  op?: string;
+}
+
+/** Context passed to startChild. */
+export interface SentrySpanContextLike {
+  description?: string;
+  instrumenter?: string;
+  startTimestamp?: number;
+  spanId?: string;
+}
+
+/** Sentry span (child or transaction). */
+export interface SentrySpanLike {
+  setStatus(s: { status?: string }): void;
+  setData(key: string, value: unknown): void;
+  finish(endTime?: number): void;
+  op?: string;
+  description?: string;
+}
+
+/** Minimal Sentry SDK interface used by the processor. */
+export interface SentryLike {
+  getCurrentHub(): SentryHubLike;
+  addGlobalEventProcessor(callback: (event: unknown) => unknown): void;
+  captureException(error: Error, options?: { contexts?: Record<string, unknown> }): void;
+}
+
+/** Client with getDsn() for isSentryRequest detection. */
+interface SentryClientLike {
+  getDsn(): { host: string } | undefined;
+}
+
+const INSTRUMENTER_OTEL = 'otel';
+
+export class SentrySpanProcessor implements SpanProcessor {
+  private readonly sentry: SentryLike;
+  private readonly map = new Map<string, SentrySpanLike | SentryTransactionLike>();
+
+  constructor(sentry: SentryLike) {
+    this.sentry = sentry;
+
+    if (typeof sentry.addGlobalEventProcessor === 'function') {
+      sentry.addGlobalEventProcessor((event: unknown) => {
+        const e = event as { contexts?: Record<string, unknown> };
+        const otelSpan = trace.getActiveSpan();
+        if (!otelSpan) return e;
+
+        if (e.contexts && (e.contexts as Record<string, unknown>).trace) {
+          return e;
+        }
+
+        const ctx = otelSpan.spanContext();
+        e.contexts = {
+          ...e.contexts,
+          trace: {
+            trace_id: ctx.traceId,
+            span_id: ctx.spanId,
+          },
+        };
+        return e;
+      });
+    }
+  }
+
+  private getDsnHost(): string | undefined {
+    const hub = this.sentry.getCurrentHub();
+    const client = (hub as unknown as { getClient?(): SentryClientLike }).getClient?.();
+    return client?.getDsn()?.host;
+  }
+
+  onStart(span: Span, _parentContext: Context): void {
+    const hub = this.sentry.getCurrentHub();
+    if (!hub) return;
+
+    const spanContext = span.spanContext();
+    const otelSpanId = spanContext.spanId;
+    const parentSpanId = span.parentSpanContext?.spanId;
+    const parentSentry = parentSpanId ? this.map.get(parentSpanId) : undefined;
+
+    const startTimestamp = convertOtelTimeToSeconds(span.startTime);
+
+    if (parentSentry && 'startChild' in parentSentry) {
+      const child = parentSentry.startChild({
+        description: span.name,
+        instrumenter: INSTRUMENTER_OTEL,
+        startTimestamp,
+        spanId: otelSpanId,
+      });
+      this.map.set(otelSpanId, child);
+    } else {
+      const traceData = getTraceData(span as unknown as ReadableSpan);
+      const transaction = hub.startTransaction({
+        name: span.name,
+        traceId: traceData.traceId,
+        spanId: traceData.spanId,
+        parentSpanId: traceData.parentSpanId,
+        startTimestamp,
+        instrumenter: INSTRUMENTER_OTEL,
+      });
+      if (transaction) {
+        this.map.set(otelSpanId, transaction);
+      }
+    }
+  }
+
+  onEnd(span: ReadableSpan): void {
+    const otelSpanId = span.spanContext().spanId;
+    const sentrySpan = this.map.get(otelSpanId);
+
+    if (isSentryRequestSpan(span, () => this.getDsnHost())) {
+      this.map.delete(otelSpanId);
+      return;
+    }
+
+    generateSentryErrorsFromOtelSpan(span, (err, opts) =>
+      this.sentry.captureException(err, opts),
+    );
+
+    if (!sentrySpan) return;
+
+    const isTransaction = 'setContext' in sentrySpan && 'finish' in sentrySpan;
+
+    if (isTransaction) {
+      updateTransactionWithOtelData(sentrySpan as SentryTransactionLike, span);
+      finishTransactionWithContextFromOtelData(
+        sentrySpan as SentryTransactionLike,
+        span,
+      );
+    } else {
+      updateSpanWithOtelData(sentrySpan as SentrySpanLike, span);
+      sentrySpan.finish(convertOtelTimeToSeconds(span.endTime));
+    }
+
+    this.map.delete(otelSpanId);
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  shutdown(): Promise<void> {
+    this.map.clear();
+    return Promise.resolve();
+  }
+}
+
+export function createSentrySpanProcessor(sentry: SentryLike): SentrySpanProcessor {
+  return new SentrySpanProcessor(sentry);
+}