autotel 2.26.3 → 3.0.3

package/src/correlated-events.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  emitCorrelatedEvent,
+  type CorrelatedEventTarget,
+} from './correlated-events';
+
+function makeTarget(opts: { withAddEvent: boolean }): {
+  target: CorrelatedEventTarget;
+  setAttribute: ReturnType<typeof vi.fn>;
+  setAttributes: ReturnType<typeof vi.fn>;
+  addEvent: ReturnType<typeof vi.fn> | undefined;
+} {
+  const setAttribute = vi.fn();
+  const setAttributes = vi.fn();
+  const addEvent = opts.withAddEvent ? vi.fn() : undefined;
+  const target: CorrelatedEventTarget = addEvent
+    ? { setAttribute, setAttributes, addEvent }
+    : { setAttribute, setAttributes };
+  return { target, setAttribute, setAttributes, addEvent };
+}
+
+describe('emitCorrelatedEvent', () => {
+  describe('addEvent path', () => {
+    it('forwards to addEvent when present and skips the attribute fallback', () => {
+      const { target, setAttribute, setAttributes, addEvent } = makeTarget({
+        withAddEvent: true,
+      });
+
+      emitCorrelatedEvent(target, 'gen_ai.prompt.sent', {
+        'gen_ai.system': 'openai',
+      });
+
+      expect(addEvent).toHaveBeenCalledTimes(1);
+      expect(addEvent).toHaveBeenCalledWith('gen_ai.prompt.sent', {
+        'gen_ai.system': 'openai',
+      });
+      expect(setAttribute).not.toHaveBeenCalled();
+      expect(setAttributes).not.toHaveBeenCalled();
+    });
+
+    it('sanitizes the event name before forwarding', () => {
+      const { target, addEvent } = makeTarget({ withAddEvent: true });
+
+      emitCorrelatedEvent(target, 'gen ai/prompt sent!', {});
+
+      expect(addEvent).toHaveBeenCalledWith('gen_ai_prompt_sent_', {});
+    });
+
+    it('preserves `this` when calling addEvent (works for prototype methods)', () => {
+      const captured: { self: unknown; args: unknown[] } = {
+        self: null,
+        args: [],
+      };
+      const target = {
+        setAttribute: vi.fn(),
+        setAttributes: vi.fn(),
+        addEvent(this: unknown, ...args: unknown[]) {
+          captured.self = this;
+          captured.args = args;
+        },
+      };
+
+      emitCorrelatedEvent(target, 'evt', { k: 'v' });
+
+      expect(captured.self).toBe(target);
+      expect(captured.args).toEqual(['evt', { k: 'v' }]);
+    });
+  });
+
+  describe('attribute fallback', () => {
+    it('writes flat, sequence-prefixed attributes when addEvent is missing', () => {
+      const { target, setAttributes } = makeTarget({ withAddEvent: false });
+
+      emitCorrelatedEvent(target, 'workflow.started', {
+        'workflow.id': 'wf-1',
+      });
+
+      expect(setAttributes).toHaveBeenCalledTimes(1);
+      const written = setAttributes.mock.calls[0]![0] as Record<
+        string,
+        unknown
+      >;
+
+      expect(written['autotel.event.1.workflow.started.name']).toBe(
+        'workflow.started',
+      );
+      expect(typeof written['autotel.event.1.workflow.started.ts']).toBe(
+        'string',
+      );
+      expect(written['autotel.event.1.workflow.started.workflow.id']).toBe(
+        'wf-1',
+      );
+    });
+
+    it('does not overwrite earlier events when the same name fires twice', () => {
+      const { target, setAttributes } = makeTarget({ withAddEvent: false });
+
+      emitCorrelatedEvent(target, 'step_retry', { 'workflow.step.attempt': 1 });
+      emitCorrelatedEvent(target, 'step_retry', { 'workflow.step.attempt': 2 });
+
+      expect(setAttributes).toHaveBeenCalledTimes(2);
+      const first = setAttributes.mock.calls[0]![0] as Record<string, unknown>;
+      const second = setAttributes.mock.calls[1]![0] as Record<string, unknown>;
+
+      expect(first['autotel.event.1.step_retry.workflow.step.attempt']).toBe(1);
+      expect(second['autotel.event.2.step_retry.workflow.step.attempt']).toBe(
+        2,
+      );
+
+      // Different keys: second call cannot overwrite the first when both
+      // attribute sets are merged on the same span.
+      expect(
+        Object.keys(first).every((k) => !Object.keys(second).includes(k)),
+      ).toBe(true);
+    });
+
+    it('sanitizes attribute keys in the fallback path', () => {
+      const { target, setAttributes } = makeTarget({ withAddEvent: false });
+
+      emitCorrelatedEvent(target, 'evt', { 'has spaces/and-bad!': 1 });
+
+      const written = setAttributes.mock.calls[0]![0] as Record<
+        string,
+        unknown
+      >;
+      const key = Object.keys(written).find((k) =>
+        k.endsWith('has_spaces_and-bad_'),
+      );
+      expect(key).toBeDefined();
+      expect(written[key!]).toBe(1);
+    });
+
+    it('keeps separate sequences for separate targets', () => {
+      const a = makeTarget({ withAddEvent: false });
+      const b = makeTarget({ withAddEvent: false });
+
+      emitCorrelatedEvent(a.target, 'evt', {});
+      emitCorrelatedEvent(b.target, 'evt', {});
+
+      const aKeys = Object.keys(
+        a.setAttributes.mock.calls[0]![0] as Record<string, unknown>,
+      );
+      const bKeys = Object.keys(
+        b.setAttributes.mock.calls[0]![0] as Record<string, unknown>,
+      );
+
+      expect(aKeys.some((k) => k.startsWith('autotel.event.1.'))).toBe(true);
+      expect(bKeys.some((k) => k.startsWith('autotel.event.1.'))).toBe(true);
+    });
+  });
+});

package/src/correlated-events.ts

@@ -0,0 +1,47 @@
+import type { AttributeValue } from './trace-context';
+
+export interface CorrelatedEventTarget {
+  setAttribute(key: string, value: AttributeValue): unknown;
+  setAttributes(attrs: Record<string, AttributeValue>): unknown;
+  addEvent?(name: string, attrs?: Record<string, AttributeValue>): unknown;
+}
+
+// OTel attribute keys are dot-namespaced flat strings; we keep `.`/`-`/`_` and
+// drop everything else so user-supplied event names can't break attribute keys.
+function sanitizeEventKey(input: string): string {
+  return input.replaceAll(/[^a-zA-Z0-9_.-]/g, '_');
+}
+
+// Per-target sequence so the fallback path can encode multiple events with the
+// same name without one overwriting the previous (attributes are
+// last-write-wins; events are not). Today the addEvent path is always taken;
+// this keeps the fallback correct if/when the runtime stops binding addEvent.
+const sequenceByTarget = new WeakMap<object, number>();
+
+function nextSequence(target: object): number {
+  const n = (sequenceByTarget.get(target) ?? 0) + 1;
+  sequenceByTarget.set(target, n);
+  return n;
+}
+
+export function emitCorrelatedEvent(
+  ctx: CorrelatedEventTarget,
+  name: string,
+  attrs: Record<string, AttributeValue> = {},
+): void {
+  const eventName = sanitizeEventKey(name);
+  if (typeof ctx.addEvent === 'function') {
+    ctx.addEvent.call(ctx, eventName, attrs);
+    return;
+  }
+  const seq = nextSequence(ctx);
+  const prefix = `autotel.event.${seq}.${eventName}`;
+  const flattened: Record<string, AttributeValue> = {
+    [`${prefix}.name`]: eventName,
+    [`${prefix}.ts`]: new Date().toISOString(),
+  };
+  for (const [k, v] of Object.entries(attrs)) {
+    flattened[`${prefix}.${sanitizeEventKey(k)}`] = v;
+  }
+  ctx.setAttributes(flattened);
+}

package/src/drain-toolkit.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { defineDrain, defineHttpDrain } from './drain-toolkit';
+
+describe('defineDrain', () => {
+  it('calls send with transformed payloads', async () => {
+    const send = vi.fn(async () => {});
+    const drain = defineDrain<
+      { event: { id: string } },
+      { key: string },
+      string
+    >({
+      name: 'test',
+      resolve: async () => ({ key: 'k' }),
+      transform: (contexts) => contexts.map((c) => c.event.id),
+      send,
+    });
+
+    await drain({ event: { id: 'a' } });
+    expect(send).toHaveBeenCalledWith(['a'], { key: 'k' });
+  });
+
+  it('skips send when resolve returns null', async () => {
+    const send = vi.fn(async () => {});
+    const drain = defineDrain({
+      name: 'test',
+      resolve: async () => null,
+      send,
+    });
+
+    await drain({ event: { id: 'a' } });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('isolates send errors', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const drain = defineDrain({
+      name: 'test',
+      resolve: async () => ({ ok: true }),
+      send: async () => {
+        throw new Error('fail');
+      },
+    });
+
+    await expect(drain({ event: { id: 'a' } })).resolves.toBeUndefined();
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('defineHttpDrain', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('encodes payload and posts via fetch', async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const drain = defineHttpDrain<
+      { event: { id: string } },
+      { token: string },
+      { id: string }
+    >({
+      name: 'http-drain',
+      resolve: async () => ({ token: 't' }),
+      transform: (contexts) => contexts.map((c) => c.event),
+      encode: (payloads, config) => ({
+        url: 'https://example.com/ingest',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(payloads),
+      }),
+      retries: 1,
+      timeoutMs: 2000,
+    });
+
+    await drain({ event: { id: 'evt_1' } });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('https://example.com/ingest');
+  });
+
+  it('retries failed requests', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network'))
+      .mockResolvedValueOnce(new Response(null, { status: 200 }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const drain = defineHttpDrain({
+      name: 'http-drain',
+      resolve: async () => ({ ok: true }),
+      encode: () => ({
+        url: 'https://example.com/ingest',
+        headers: { 'content-type': 'application/json' },
+        body: '[]',
+      }),
+      retries: 2,
+      timeoutMs: 2000,
+    });
+
+    await drain({ event: { id: 'evt_1' } });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/drain-toolkit.ts

@@ -0,0 +1,129 @@
+export interface DrainOptions<TContext, TConfig, TPayload = TContext> {
+  /** Stable identifier used in error logs. */
+  name: string;
+  /** Return null to skip draining (e.g. missing API key in dev). */
+  resolve: () => TConfig | null | Promise<TConfig | null>;
+  /** Transform contexts into payloads. Defaults to identity. */
+  transform?: (contexts: TContext[]) => TPayload[];
+  /** Transport implementation. */
+  send: (payloads: TPayload[], config: TConfig) => Promise<void>;
+}
+
+export interface HttpDrainRequest {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+export interface HttpDrainOptions<
+  TContext,
+  TConfig,
+  TPayload = TContext,
+> extends Omit<DrainOptions<TContext, TConfig, TPayload>, 'send'> {
+  encode: (payloads: TPayload[], config: TConfig) => HttpDrainRequest | null;
+  timeoutMs?: number;
+  retries?: number;
+  resolveTimeoutMs?: (config: TConfig) => number | undefined;
+  resolveRetries?: (config: TConfig) => number | undefined;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_RETRIES = 2;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+  });
+}
+
+async function postWithRetry(options: {
+  name: string;
+  request: HttpDrainRequest;
+  timeoutMs: number;
+  retries: number;
+}): Promise<void> {
+  const { name, request, timeoutMs, retries } = options;
+  const attempts = Math.max(1, retries);
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+      const response = await fetch(request.url, {
+        method: 'POST',
+        headers: request.headers,
+        body: request.body,
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        throw new Error(
+          `[autotel/${name}] HTTP ${response.status} draining ${request.url}`,
+        );
+      }
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < attempts) {
+        await delay(100 * attempt);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw lastError;
+}
+
+export function defineDrain<TContext, TConfig, TPayload = TContext>(
+  options: DrainOptions<TContext, TConfig, TPayload>,
+): (ctx: TContext | TContext[]) => Promise<void> {
+  return async (ctx: TContext | TContext[]) => {
+    const contexts = Array.isArray(ctx) ? ctx : [ctx];
+    if (contexts.length === 0) return;
+
+    const config = await options.resolve();
+    if (!config) return;
+
+    const payloads = options.transform
+      ? options.transform(contexts)
+      : (contexts as unknown as TPayload[]);
+
+    if (payloads.length === 0) return;
+
+    try {
+      await options.send(payloads, config);
+    } catch (error) {
+      console.error(`[autotel/${options.name}] drain failed:`, error);
+    }
+  };
+}
+
+export function defineHttpDrain<TContext, TConfig, TPayload = TContext>(
+  options: HttpDrainOptions<TContext, TConfig, TPayload>,
+): (ctx: TContext | TContext[]) => Promise<void> {
+  return defineDrain<TContext, TConfig, TPayload>({
+    name: options.name,
+    resolve: options.resolve,
+    transform: options.transform,
+    send: async (payloads, config) => {
+      const request = options.encode(payloads, config);
+      if (!request) return;
+      const timeoutMs =
+        options.resolveTimeoutMs?.(config) ??
+        options.timeoutMs ??
+        DEFAULT_TIMEOUT_MS;
+      const retries =
+        options.resolveRetries?.(config) ?? options.retries ?? DEFAULT_RETRIES;
+
+      await postWithRetry({
+        name: options.name,
+        request,
+        timeoutMs,
+        retries,
+      });
+    },
+  });
+}

package/src/enricher-toolkit.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi } from 'vitest';
+import { defineEnricher } from './enricher-toolkit';
+
+describe('defineEnricher', () => {
+  it('merges computed values into existing field by default', () => {
+    const enricher = defineEnricher({
+      name: 'tenant-enricher',
+      field: 'tenant',
+      compute: () => ({ plan: 'pro' }),
+    });
+
+    const ctx = {
+      event: { tenant: { id: 't_1' } },
+    };
+
+    enricher(ctx);
+    expect(ctx.event).toEqual({ tenant: { id: 't_1', plan: 'pro' } });
+  });
+
+  it('overwrites field when overwrite=true', () => {
+    const enricher = defineEnricher(
+      {
+        name: 'tenant-enricher',
+        field: 'tenant',
+        compute: () => ({ plan: 'pro' }),
+      },
+      { overwrite: true },
+    );
+
+    const ctx = {
+      event: { tenant: { id: 't_1' } },
+    };
+
+    enricher(ctx);
+    expect(ctx.event).toEqual({ tenant: { plan: 'pro' } });
+  });
+
+  it('skips enrichment when compute returns undefined', () => {
+    const enricher = defineEnricher({
+      name: 'noop-enricher',
+      field: 'tenant',
+      compute: () => undefined,
+    });
+
+    const ctx = { event: { a: 1 } as Record<string, unknown> };
+    enricher(ctx);
+    expect(ctx.event).toEqual({ a: 1 });
+  });
+
+  it('isolates compute errors and logs them', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const enricher = defineEnricher({
+      name: 'broken-enricher',
+      field: 'tenant',
+      compute: () => {
+        throw new Error('boom');
+      },
+    });
+
+    const ctx = { event: {} as Record<string, unknown> };
+    enricher(ctx);
+
+    expect(ctx.event).toEqual({});
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/src/enricher-toolkit.ts

@@ -0,0 +1,79 @@
+export interface EnrichContext<TEvent extends Record<string, unknown>> {
+  event: TEvent;
+  request?: {
+    method?: string;
+    path?: string;
+    requestId?: string;
+  };
+  response?: {
+    status?: number;
+  };
+  headers?: Record<string, string>;
+}
+
+export interface EnricherDefinition<
+  TEvent extends Record<string, unknown>,
+  TValue extends object,
+> {
+  /** Stable identifier used in error logs. */
+  name: string;
+  /** Top-level field to merge computed values into. */
+  field: keyof TEvent & string;
+  /** Return undefined to skip enrichment. */
+  compute: (ctx: EnrichContext<TEvent>) => TValue | undefined;
+}
+
+export interface EnricherOptions {
+  /** Replace existing field value instead of merge. Default false. */
+  overwrite?: boolean;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeInto(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): void {
+  for (const key in source) {
+    const sourceVal = source[key];
+    if (sourceVal === undefined) continue;
+    const targetVal = target[key];
+    if (isPlainObject(sourceVal) && isPlainObject(targetVal)) {
+      mergeInto(targetVal, sourceVal);
+    } else {
+      target[key] = sourceVal;
+    }
+  }
+}
+
+export function defineEnricher<
+  TEvent extends Record<string, unknown>,
+  TValue extends object,
+>(
+  def: EnricherDefinition<TEvent, TValue>,
+  options: EnricherOptions = {},
+): (ctx: EnrichContext<TEvent>) => void {
+  return (ctx: EnrichContext<TEvent>) => {
+    let computed: TValue | undefined;
+    try {
+      computed = def.compute(ctx);
+    } catch (error) {
+      console.error(`[autotel/${def.name}] enrich failed:`, error);
+      return;
+    }
+
+    if (!computed) return;
+
+    if (options.overwrite || !isPlainObject(ctx.event[def.field])) {
+      (ctx.event as Record<string, unknown>)[def.field] = computed;
+      return;
+    }
+
+    mergeInto(
+      ctx.event[def.field] as unknown as Record<string, unknown>,
+      computed as unknown as Record<string, unknown>,
+    );
+  };
+}

package/src/functional.ts

@@ -422,6 +422,8 @@ const MAX_ERROR_MESSAGE_LENGTH = 500;
 function createDummyCtx<
   TBaggage extends Record<string, unknown> | undefined = undefined,
 >(): TraceContext<TBaggage> {
+  // `recordException` / `addEvent` are no-op shims kept for the same
+  // compatibility window as `createTraceContext` (see trace-context.ts).
   return {
     traceId: '',
     spanId: '',

package/src/gen-ai-events.ts

@@ -42,6 +42,7 @@
  */
 
 import type { TraceContext } from './trace-context';
+import { emitCorrelatedEvent } from './correlated-events';
 
 type EventAttrs = Record<string, string | number | boolean>;
 
@@ -102,7 +103,7 @@ export function recordPromptSent(
   ctx: TraceContext,
   event: PromptSentEvent = {},
 ): void {
-  ctx.addEvent('gen_ai.prompt.sent', buildPromptSentAttrs(event));
+  emitCorrelatedEvent(ctx, 'gen_ai.prompt.sent', buildPromptSentAttrs(event));
 }
 
 /**
@@ -113,7 +114,11 @@ export function recordResponseReceived(
   ctx: TraceContext,
   event: ResponseReceivedEvent = {},
 ): void {
-  ctx.addEvent('gen_ai.response.received', buildResponseAttrs(event));
+  emitCorrelatedEvent(
+    ctx,
+    'gen_ai.response.received',
+    buildResponseAttrs(event),
+  );
 }
 
 /**
@@ -122,7 +127,7 @@ export function recordResponseReceived(
  * decision was made.
  */
 export function recordRetry(ctx: TraceContext, event: RetryEvent): void {
-  ctx.addEvent('gen_ai.retry', buildRetryAttrs(event));
+  emitCorrelatedEvent(ctx, 'gen_ai.retry', buildRetryAttrs(event));
 }
 
 /**
@@ -131,7 +136,7 @@ export function recordRetry(ctx: TraceContext, event: RetryEvent): void {
  * several tool calls within a single provider response.
  */
 export function recordToolCall(ctx: TraceContext, event: ToolCallEvent): void {
-  ctx.addEvent('gen_ai.tool.call', buildToolCallAttrs(event));
+  emitCorrelatedEvent(ctx, 'gen_ai.tool.call', buildToolCallAttrs(event));
 }
 
 /**
@@ -143,7 +148,11 @@ export function recordStreamFirstToken(
   ctx: TraceContext,
   event: StreamFirstTokenEvent = {},
 ): void {
-  ctx.addEvent('gen_ai.stream.first_token', buildStreamFirstTokenAttrs(event));
+  emitCorrelatedEvent(
+    ctx,
+    'gen_ai.stream.first_token',
+    buildStreamFirstTokenAttrs(event),
+  );
 }
 
 // ---- Attribute builders -------------------------------------------------