autotel 4.0.0 → 4.2.0

package/src/tail-sampling-processor.test.ts

@@ -1,230 +0,0 @@
-/**
- * Tests for tail sampling span processor
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import { TailSamplingSpanProcessor } from './tail-sampling-processor';
-import {
-  AUTOTEL_SAMPLING_TAIL_KEEP,
-  AUTOTEL_SAMPLING_TAIL_EVALUATED,
-} from './sampling';
-import type {
-  SpanProcessor,
-  ReadableSpan,
-} from '@opentelemetry/sdk-trace-base';
-import type { Context } from '@opentelemetry/api';
-import type { Span } from '@opentelemetry/sdk-trace-base';
-
-// Mock span processor
-class MockSpanProcessor implements SpanProcessor {
-  public startedSpans: Span[] = [];
-  public endedSpans: ReadableSpan[] = [];
-  public flushed = false;
-  public shutdownCalled = false;
-
-  onStart(span: Span): void {
-    this.startedSpans.push(span);
-  }
-
-  onEnd(span: ReadableSpan): void {
-    this.endedSpans.push(span);
-  }
-
-  async forceFlush(): Promise<void> {
-    this.flushed = true;
-  }
-
-  async shutdown(): Promise<void> {
-    this.shutdownCalled = true;
-  }
-
-  reset(): void {
-    this.startedSpans = [];
-    this.endedSpans = [];
-    this.flushed = false;
-    this.shutdownCalled = false;
-  }
-}
-
-// Create mock ReadableSpan
-function createMockSpan(attributes: Record<string, unknown>): ReadableSpan {
-  return {
-    attributes,
-    name: 'test-span',
-    spanContext: () => ({
-      traceId: 'trace123',
-      spanId: 'span123',
-      traceFlags: 1,
-    }),
-  } as ReadableSpan;
-}
-
-describe('TailSamplingSpanProcessor', () => {
-  let mockProcessor: MockSpanProcessor;
-  let tailSamplingProcessor: TailSamplingSpanProcessor;
-
-  beforeEach(() => {
-    mockProcessor = new MockSpanProcessor();
-    tailSamplingProcessor = new TailSamplingSpanProcessor(mockProcessor);
-  });
-
-  describe('Span forwarding', () => {
-    it('should forward span to wrapped processor on onStart', () => {
-      const mockSpan = {} as Span;
-      const mockContext = {} as Context;
-
-      tailSamplingProcessor.onStart(mockSpan, mockContext);
-
-      expect(mockProcessor.startedSpans).toHaveLength(1);
-      expect(mockProcessor.startedSpans[0]).toBe(mockSpan);
-    });
-
-    it('should forward spans without tail sampling attributes', () => {
-      const span = createMockSpan({ foo: 'bar' });
-
-      tailSamplingProcessor.onEnd(span);
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0]).toBe(span);
-    });
-
-    it('should forward spans marked to keep (sampling.tail.keep = true)', () => {
-      const span = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: true,
-      });
-
-      tailSamplingProcessor.onEnd(span);
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0]).toBe(span);
-    });
-  });
-
-  describe('Span dropping', () => {
-    it('should drop spans marked to drop (sampling.tail.keep = false)', () => {
-      const span = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
-      });
-
-      tailSamplingProcessor.onEnd(span);
-
-      // Span should NOT be forwarded
-      expect(mockProcessor.endedSpans).toHaveLength(0);
-    });
-
-    it('should drop multiple spans marked as false', () => {
-      const span1 = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
-      });
-
-      const span2 = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
-      });
-
-      tailSamplingProcessor.onEnd(span1);
-      tailSamplingProcessor.onEnd(span2);
-
-      expect(mockProcessor.endedSpans).toHaveLength(0);
-    });
-  });
-
-  describe('Edge cases', () => {
-    it('should forward spans when only evaluated but no keep attribute', () => {
-      const span = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        // Missing AUTOTEL_SAMPLING_TAIL_KEEP
-      });
-
-      tailSamplingProcessor.onEnd(span);
-
-      // Should forward (undefined !== false)
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-    });
-
-    it('should forward spans when only keep but not evaluated', () => {
-      const span = createMockSpan({
-        // Missing AUTOTEL_SAMPLING_TAIL_EVALUATED
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
-      });
-
-      tailSamplingProcessor.onEnd(span);
-
-      // Should forward (evaluated !== true)
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-    });
-
-    it('should handle mixed spans (some kept, some dropped)', () => {
-      const keptSpan1 = createMockSpan({ foo: 'bar' });
-      const droppedSpan = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
-      });
-      const keptSpan2 = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: true,
-      });
-
-      tailSamplingProcessor.onEnd(keptSpan1);
-      tailSamplingProcessor.onEnd(droppedSpan);
-      tailSamplingProcessor.onEnd(keptSpan2);
-
-      expect(mockProcessor.endedSpans).toHaveLength(2);
-      expect(mockProcessor.endedSpans[0]).toBe(keptSpan1);
-      expect(mockProcessor.endedSpans[1]).toBe(keptSpan2);
-    });
-  });
-
-  describe('Lifecycle methods', () => {
-    it('should forward forceFlush to wrapped processor', async () => {
-      await tailSamplingProcessor.forceFlush();
-
-      expect(mockProcessor.flushed).toBe(true);
-    });
-
-    it('should forward shutdown to wrapped processor', async () => {
-      await tailSamplingProcessor.shutdown();
-
-      expect(mockProcessor.shutdownCalled).toBe(true);
-    });
-  });
-
-  describe('Integration with sampling strategy', () => {
-    it('should work with adaptive sampling pattern', () => {
-      // Simulate adaptive sampling flow:
-      // 1. Fast successful request (drop)
-      // 2. Slow request (keep)
-      // 3. Error request (keep)
-
-      const fastSpan = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: false, // Fast, no errors
-        duration: 50,
-      });
-
-      const slowSpan = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: true, // Slow request
-        duration: 1000,
-      });
-
-      const errorSpan = createMockSpan({
-        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
-        [AUTOTEL_SAMPLING_TAIL_KEEP]: true, // Had error
-        error: true,
-      });
-
-      tailSamplingProcessor.onEnd(fastSpan);
-      tailSamplingProcessor.onEnd(slowSpan);
-      tailSamplingProcessor.onEnd(errorSpan);
-
-      // Only slow and error spans should be forwarded
-      expect(mockProcessor.endedSpans).toHaveLength(2);
-      expect(mockProcessor.endedSpans[0]).toBe(slowSpan);
-      expect(mockProcessor.endedSpans[1]).toBe(errorSpan);
-    });
-  });
-});

package/src/tail-sampling-processor.ts

@@ -1,55 +0,0 @@
-/**
- * Tail Sampling Span Processor
- *
- * Filters spans based on the `autotel.sampling.tail.keep` attribute set during execution.
- * This enables adaptive sampling where we decide whether to keep a span AFTER
- * the operation completes, based on criteria like errors, duration, etc.
- *
- * How it works:
- * 1. Decorator creates span optimistically (head sampling returns true)
- * 2. Operation executes and completes
- * 3. Decorator calls shouldKeepTrace() and sets autotel.sampling.tail.keep attribute
- * 4. This processor checks the attribute and drops spans marked as false
- */
-
-import type {
-  SpanProcessor,
-  ReadableSpan,
-} from '@opentelemetry/sdk-trace-base';
-import type { Context } from '@opentelemetry/api';
-import type { Span } from '@opentelemetry/sdk-trace-base';
-import {
-  AUTOTEL_SAMPLING_TAIL_KEEP,
-  AUTOTEL_SAMPLING_TAIL_EVALUATED,
-} from './sampling';
-
-export class TailSamplingSpanProcessor implements SpanProcessor {
-  private wrappedProcessor: SpanProcessor;
-
-  constructor(wrappedProcessor: SpanProcessor) {
-    this.wrappedProcessor = wrappedProcessor;
-  }
-
-  onStart(span: Span, parentContext: Context): void {
-    this.wrappedProcessor.onStart(span, parentContext);
-  }
-
-  onEnd(span: ReadableSpan): void {
-    const tailEvaluated = span.attributes[AUTOTEL_SAMPLING_TAIL_EVALUATED];
-    const shouldKeep = span.attributes[AUTOTEL_SAMPLING_TAIL_KEEP];
-
-    if (tailEvaluated === true && shouldKeep === false) {
-      return;
-    }
-
-    this.wrappedProcessor.onEnd(span);
-  }
-
-  forceFlush(): Promise<void> {
-    return this.wrappedProcessor.forceFlush();
-  }
-
-  shutdown(): Promise<void> {
-    return this.wrappedProcessor.shutdown();
-  }
-}

package/src/test-span-collector.test.ts

@@ -1,234 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { SpanStatusCode } from '@opentelemetry/api';
-import { TestSpanCollector, type SerializedSpan } from './test-span-collector';
-
-/** Helper to create a minimal ReadableSpan mock */
-function makeSpan(opts: {
-  traceId: string;
-  spanId: string;
-  parentSpanId?: string;
-  name: string;
-  startTime?: [number, number];
-  duration?: [number, number];
-  statusCode?: number;
-  statusMessage?: string;
-  attributes?: Record<string, unknown>;
-}) {
-  return {
-    spanContext: () => ({ traceId: opts.traceId, spanId: opts.spanId }),
-    parentSpanContext: opts.parentSpanId
-      ? { spanId: opts.parentSpanId }
-      : undefined,
-    name: opts.name,
-    startTime: opts.startTime ?? [1000, 500_000_000],
-    duration: opts.duration ?? [0, 100_000_000],
-    status: {
-      code: opts.statusCode ?? SpanStatusCode.UNSET,
-      message: opts.statusMessage ?? '',
-    },
-    attributes: opts.attributes ?? {},
-  } as any;
-}
-
-describe('TestSpanCollector', () => {
-  it('groups spans by traceId', () => {
-    const collector = new TestSpanCollector();
-
-    const callback = vi.fn();
-    collector.export(
-      [
-        makeSpan({ traceId: 'trace-a', spanId: 'span-1', name: 'op1' }),
-        makeSpan({ traceId: 'trace-b', spanId: 'span-2', name: 'op2' }),
-        makeSpan({
-          traceId: 'trace-a',
-          spanId: 'span-3',
-          parentSpanId: 'span-1',
-          name: 'op3',
-        }),
-      ],
-      callback,
-    );
-
-    expect(callback).toHaveBeenCalledWith({ code: 0 }); // ExportResultCode.SUCCESS
-
-    const traceA = collector.drainTrace('trace-a', 'span-1');
-    expect(traceA).toHaveLength(2);
-    expect(traceA.map((s) => s.name)).toEqual(
-      expect.arrayContaining(['op1', 'op3']),
-    );
-
-    const traceB = collector.drainTrace('trace-b', 'span-2');
-    expect(traceB).toHaveLength(1);
-    expect(traceB[0].name).toBe('op2');
-  });
-
-  it('drainTrace returns only descendants of rootSpanId', () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [
-        makeSpan({ traceId: 't1', spanId: 'root', name: 'test:mytest' }),
-        makeSpan({
-          traceId: 't1',
-          spanId: 'child1',
-          parentSpanId: 'root',
-          name: 'child-op',
-        }),
-        makeSpan({
-          traceId: 't1',
-          spanId: 'grandchild',
-          parentSpanId: 'child1',
-          name: 'grandchild-op',
-        }),
-        makeSpan({ traceId: 't1', spanId: 'other-root', name: 'other-test' }),
-        makeSpan({
-          traceId: 't1',
-          spanId: 'other-child',
-          parentSpanId: 'other-root',
-          name: 'other-child-op',
-        }),
-      ],
-      vi.fn(),
-    );
-
-    const spans = collector.drainTrace('t1', 'root');
-    expect(spans).toHaveLength(3);
-    const names = spans.map((s) => s.name);
-    expect(names).toContain('test:mytest');
-    expect(names).toContain('child-op');
-    expect(names).toContain('grandchild-op');
-    expect(names).not.toContain('other-test');
-    expect(names).not.toContain('other-child-op');
-  });
-
-  it('returns [] for unknown traceId', () => {
-    const collector = new TestSpanCollector();
-    expect(collector.drainTrace('nonexistent', 'any-span')).toEqual([]);
-  });
-
-  it('converts HrTime to ms and maps status codes', () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [
-        makeSpan({
-          traceId: 't',
-          spanId: 's1',
-          name: 'ok-span',
-          startTime: [100, 250_000_000],
-          duration: [1, 500_000_000],
-          statusCode: SpanStatusCode.OK,
-        }),
-        makeSpan({
-          traceId: 't',
-          spanId: 's2',
-          parentSpanId: 's1',
-          name: 'error-span',
-          startTime: [200, 0],
-          duration: [0, 50_000_000],
-          statusCode: SpanStatusCode.ERROR,
-          statusMessage: 'something failed',
-        }),
-      ],
-      vi.fn(),
-    );
-
-    const spans = collector.drainTrace('t', 's1');
-    const okSpan = spans.find((s) => s.name === 'ok-span')!;
-    const errSpan = spans.find((s) => s.name === 'error-span')!;
-
-    expect(okSpan.startTimeMs).toBe(100_250);
-    expect(okSpan.durationMs).toBe(1500);
-    expect(okSpan.status).toBe('ok');
-    expect(okSpan.statusMessage).toBeUndefined();
-
-    expect(errSpan.startTimeMs).toBe(200_000);
-    expect(errSpan.durationMs).toBe(50);
-    expect(errSpan.status).toBe('error');
-    expect(errSpan.statusMessage).toBe('something failed');
-  });
-
-  it('keeps string/number/boolean + arrays of primitives, drops others', () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [
-        makeSpan({
-          traceId: 't',
-          spanId: 's',
-          name: 'attr-test',
-          attributes: {
-            str: 'hello',
-            num: 42,
-            bool: true,
-            strArr: ['a', 'b'],
-            numArr: [1, 2, 3],
-            boolArr: [true, false],
-            nested: { key: 'value' }, // should be dropped
-            mixed: [1, 'two'], // should be dropped (mixed types)
-            empty: [], // should be dropped (empty array)
-            undef: undefined,
-          },
-        }),
-      ],
-      vi.fn(),
-    );
-
-    const spans = collector.drainTrace('t', 's');
-    expect(spans).toHaveLength(1);
-    const attrs = spans[0].attributes!;
-    expect(attrs.str).toBe('hello');
-    expect(attrs.num).toBe(42);
-    expect(attrs.bool).toBe(true);
-    expect(attrs.strArr).toEqual(['a', 'b']);
-    expect(attrs.numArr).toEqual([1, 2, 3]);
-    expect(attrs.boolArr).toEqual([true, false]);
-    expect(attrs).not.toHaveProperty('nested');
-    expect(attrs).not.toHaveProperty('mixed');
-    expect(attrs).not.toHaveProperty('empty');
-    expect(attrs).not.toHaveProperty('undef');
-  });
-
-  it('omits attributes field when span has no serializable attributes', () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [
-        makeSpan({
-          traceId: 't',
-          spanId: 's',
-          name: 'no-attrs',
-          attributes: {},
-        }),
-      ],
-      vi.fn(),
-    );
-
-    const spans = collector.drainTrace('t', 's');
-    expect(spans[0].attributes).toBeUndefined();
-  });
-
-  it('clears all data on shutdown', async () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [makeSpan({ traceId: 't', spanId: 's', name: 'op' })],
-      vi.fn(),
-    );
-
-    await collector.shutdown();
-    expect(collector.drainTrace('t', 's')).toEqual([]);
-  });
-
-  it('drain removes the trace entry so second drain returns []', () => {
-    const collector = new TestSpanCollector();
-
-    collector.export(
-      [makeSpan({ traceId: 't', spanId: 's', name: 'op' })],
-      vi.fn(),
-    );
-
-    expect(collector.drainTrace('t', 's')).toHaveLength(1);
-    expect(collector.drainTrace('t', 's')).toEqual([]);
-  });
-});

package/src/test-span-collector.ts

@@ -1,150 +0,0 @@
-/**
- * TestSpanCollector — SpanExporter that groups finished spans by traceId
- * and drains per-trace for embedding in test metadata.
- *
- * @example
- * ```typescript
- * import { TestSpanCollector } from 'autotel/test-span-collector';
- * import { SimpleSpanProcessor } from 'autotel/processors';
- * import { getAutotelTracerProvider } from 'autotel';
- *
- * const collector = new TestSpanCollector();
- * const provider = getAutotelTracerProvider();
- * provider.addSpanProcessor(new SimpleSpanProcessor(collector));
- *
- * // After a test span ends:
- * const spans = collector.drainTrace(traceId, rootSpanId);
- * // spans contains only descendants of rootSpanId
- * ```
- */
-
-import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { SpanStatusCode } from '@opentelemetry/api';
-
-/** @see ExportResultCode from @opentelemetry/core */
-const ExportResultCode = { SUCCESS: 0, FAILED: 1 } as const;
-
-/** Attribute value types that survive serialization */
-type SerializableValue =
-  | string
-  | number
-  | boolean
-  | string[]
-  | number[]
-  | boolean[];
-
-/**
- * Portable serialized span for embedding in test metadata.
- * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.
- *
- * Defined as a `type` (not `interface`) so it is assignable to
- * `Record<string, unknown>` in TypeScript 6+ strict mode.
- */
-export type SerializedSpan = {
-  spanId: string;
-  parentSpanId?: string;
-  name: string;
-  startTimeMs: number;
-  durationMs: number;
-  status: 'ok' | 'error' | 'unset';
-  statusMessage?: string;
-  attributes?: Record<string, SerializableValue>;
-};
-
-export class TestSpanCollector implements SpanExporter {
-  private traces = new Map<string, ReadableSpan[]>();
-
-  export(
-    spans: ReadableSpan[],
-    callback: (result: { code: number }) => void,
-  ): void {
-    for (const span of spans) {
-      const traceId = span.spanContext().traceId;
-      let list = this.traces.get(traceId);
-      if (!list) {
-        list = [];
-        this.traces.set(traceId, list);
-      }
-      list.push(span);
-    }
-    callback({ code: ExportResultCode.SUCCESS });
-  }
-
-  /**
-   * Drain and serialize spans that are descendants of `rootSpanId` within `traceId`.
-   * Filters to the subtree rooted at the test span to prevent cross-test mixing.
-   * Removes the entire traceId entry from the collector.
-   */
-  drainTrace(traceId: string, rootSpanId: string): SerializedSpan[] {
-    const allSpans = this.traces.get(traceId);
-    this.traces.delete(traceId);
-    if (!allSpans?.length) return [];
-
-    // Build spanId → span index for efficient parent-chain walking
-    const byId = new Map<string, ReadableSpan>();
-    for (const s of allSpans) byId.set(s.spanContext().spanId, s);
-
-    // Filter to spans that are the root or descendants of rootSpanId
-    const included = allSpans.filter((s) => {
-      let id: string | undefined = s.spanContext().spanId;
-      while (id) {
-        if (id === rootSpanId) return true;
-        const parent = byId.get(id);
-        const parentId = parent?.parentSpanContext?.spanId || undefined;
-        if (parentId === id) break; // cycle guard
-        id = parentId;
-      }
-      return false;
-    });
-
-    return included.map((s) => serializeSpan(s));
-  }
-
-  shutdown(): Promise<void> {
-    this.traces.clear();
-    return Promise.resolve();
-  }
-
-  forceFlush(): Promise<void> {
-    return Promise.resolve();
-  }
-}
-
-function hrTimeToMs(hr: [number, number]): number {
-  return hr[0] * 1000 + hr[1] / 1_000_000;
-}
-
-function isSerializable(v: unknown): v is SerializableValue {
-  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
-    return true;
-  if (Array.isArray(v) && v.length > 0) {
-    const t = typeof v[0];
-    return (
-      (t === 'string' || t === 'number' || t === 'boolean') &&
-      v.every((e) => typeof e === t)
-    );
-  }
-  return false;
-}
-
-export function serializeSpan(span: ReadableSpan): SerializedSpan {
-  const attrs: Record<string, SerializableValue> = {};
-  for (const [k, v] of Object.entries(span.attributes)) {
-    if (isSerializable(v)) attrs[k] = v;
-  }
-  return {
-    spanId: span.spanContext().spanId,
-    parentSpanId: span.parentSpanContext?.spanId || undefined,
-    name: span.name,
-    startTimeMs: hrTimeToMs(span.startTime as [number, number]),
-    durationMs: hrTimeToMs(span.duration as [number, number]),
-    status:
-      span.status.code === SpanStatusCode.ERROR
-        ? 'error'
-        : span.status.code === SpanStatusCode.OK
-          ? 'ok'
-          : 'unset',
-    statusMessage: span.status.message || undefined,
-    attributes: Object.keys(attrs).length > 0 ? attrs : undefined,
-  };
-}