autotel 2.26.0 → 2.26.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AutotelConfig, i as init } from './init-FiR_glVc.js';
+export { A as AutotelConfig, i as init, a as isLoggerLocked, l as lockLogger } from './init-D6JfWEjL.js';
 import { Span, Context } from '@opentelemetry/api';
 export { Context, ROOT_CONTEXT, Span, SpanContext, SpanKind, Link as SpanLink, SpanStatusCode, TextMapGetter, TextMapSetter, Tracer, context, trace as otelTrace, propagation } from '@opentelemetry/api';
 import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
@@ -18,6 +18,7 @@ export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSa
 export { Event, EventsOptions, getEvents, resetEvents } from './event.js';
 export { Metric, MetricsOptions, getMetrics, resetMetrics } from './metric.js';
 export { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from './metric-helpers.js';
+import { ViewOptions } from '@opentelemetry/sdk-metrics';
 export { TraceContext as OtelTraceContext, createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, resolveTraceUrl, runWithSpan } from './trace-helpers.js';
 export { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from './tracer-provider.js';
 export { DBConfig, HTTPConfig, LLMConfig, MessagingConfig, traceDB, traceHTTP, traceLLM, traceMessaging } from './semantic-helpers.js';
@@ -30,7 +31,6 @@ import '@opentelemetry/sdk-node';
 import '@opentelemetry/resources';
 import './logger.js';
 import 'pino';
-import '@opentelemetry/sdk-metrics';
 import '@opentelemetry/sdk-logs';
 import './processors.js';
 import 'node:async_hooks';
@@ -428,6 +428,7 @@ interface RequestLogger {
     error(error: Error | string, fields?: Record<string, unknown>): void;
     getContext(): Record<string, unknown>;
     emitNow(overrides?: Record<string, unknown>): RequestLogSnapshot;
+    fork(label: string, fn: () => void | Promise<void>): void;
 }
 interface RequestLogSnapshot {
     timestamp: string;
@@ -452,6 +453,8 @@ interface StructuredErrorInput {
     cause?: unknown;
     details?: Record<string, unknown>;
     name?: string;
+    /** Backend-only context. Omitted from toJSON() and never serialized to clients. */
+    internal?: Record<string, unknown>;
 }
 interface StructuredError extends Error {
     why?: string;
@@ -460,8 +463,11 @@ interface StructuredError extends Error {
     code?: string | number;
     status?: number;
     details?: Record<string, unknown>;
+    /** Backend-only context. Omitted from toJSON() and never serialized to clients. */
+    readonly internal?: Record<string, unknown>;
 }
 declare function createStructuredError(input: StructuredErrorInput): StructuredError;
+declare function structuredErrorToJSON(error: StructuredError): Record<string, unknown>;
 declare function getStructuredErrorAttributes(error: Error): Record<string, AttributeValue>;
 declare function recordStructuredError(ctx: Pick<TraceContext, 'recordException' | 'setAttributes' | 'setStatus'>, error: Error): void;
 
@@ -486,4 +492,200 @@ declare function flattenToAttributes(fields: Record<string, unknown>, prefix?: s
  */
 declare function formatDuration(ms: number): string;
 
-export { AttributeRedactorConfig, AttributeRedactorPreset, BaggageSpanProcessor, type BaggageSpanProcessorOptions, EventAttributes, EventSubscriber, type OperationContext, type RequestLogSnapshot, type RequestLogger, type RequestLoggerOptions, type StringRedactor, type StructuredError, type StructuredErrorInput, TraceContext, createStringRedactor, createStructuredError, flattenToAttributes, flush, formatDuration, getEventQueue, getOperationContext, getRequestLogger, getStructuredErrorAttributes, recordStructuredError, runInOperationContext, runWithRequestContext, shutdown, toAttributeValue, track };
+/**
+ * LLM-tuned histogram buckets.
+ *
+ * Default OpenTelemetry histogram buckets target HTTP latency (0ms–10s)
+ * and small counter values. LLM workloads have very different shapes:
+ *
+ *   - **Duration**: single-token prompts can be fast (50ms), long
+ *     generations and reasoning models can run for minutes. Default buckets
+ *     crush everything above 10s into one bucket.
+ *   - **Token usage**: heavily right-skewed. A single request can range
+ *     from tens of tokens to the million-token context windows.
+ *   - **Cost (USD)**: per-request values are tiny (fractions of a cent),
+ *     so linear buckets waste resolution at the low end.
+ *
+ * This module exposes empirically-chosen bucket arrays and a View helper
+ * so users can apply them to their `MeterProvider` without knowing the
+ * exact instrument names emitted by OpenAI/Anthropic/Traceloop plugins.
+ *
+ * @example
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { genAiMetricViews } from 'autotel';
+ *
+ * const sdk = new NodeSDK({
+ *   serviceName: 'my-agent',
+ *   views: [...genAiMetricViews()],
+ * });
+ * sdk.start();
+ * ```
+ */
+
+/**
+ * Duration buckets for LLM operations, in **seconds**. Covers fast
+ * completions (50ms) through long-running reasoning jobs (5 min).
+ *
+ * Aligns with the OTel GenAI semantic conventions' published advice for
+ * `gen_ai.client.operation.duration`.
+ */
+declare const GEN_AI_DURATION_BUCKETS_SECONDS: readonly number[];
+/**
+ * Token-count buckets for prompt, completion, and total token histograms.
+ * Ranges from tiny prompts to million-token context windows.
+ *
+ * Aligns with the OTel GenAI semantic conventions' published advice for
+ * `gen_ai.client.token.usage`.
+ */
+declare const GEN_AI_TOKEN_USAGE_BUCKETS: readonly number[];
+/**
+ * USD cost buckets. Sub-cent resolution at the low end (fractions of a
+ * cent per small call) up to tens of dollars (batch jobs, Opus/o1 runs).
+ */
+declare const GEN_AI_COST_USD_BUCKETS: readonly number[];
+/**
+ * Instrument-level advice object for `createHistogram(name, advice)`.
+ * Use when you control the instrument creation (e.g. custom business
+ * LLM metrics); `genAiMetricViews()` is better when the metric comes
+ * from a third-party plugin.
+ */
+declare function llmHistogramAdvice(kind: 'duration' | 'tokens' | 'cost'): {
+    advice: {
+        explicitBucketBoundaries: number[];
+    };
+};
+/**
+ * Returns `View`s that re-bucket the standard OTel GenAI histograms. Pass
+ * the result to your `MeterProvider`'s `views` option.
+ *
+ * Matches instrument names emitted by:
+ * - OpenTelemetry GenAI autoinstrumentation
+ * - OpenInference / OpenLLMetry (traceloop)
+ * - Arize Phoenix, LangSmith, etc. that follow the OTel spec
+ *
+ * Add more instrument patterns via the `extra` argument if you emit
+ * custom LLM metrics.
+ */
+declare function genAiMetricViews(extra?: {
+    instrumentName: string;
+    kind: 'duration' | 'tokens' | 'cost';
+}[]): ViewOptions[];
+
+/**
+ * Span event helpers for LLM lifecycle, aligned with the OpenTelemetry
+ * GenAI semantic conventions.
+ *
+ * Span events are timestamped points within a span — they render as dots
+ * on the trace timeline in Jaeger / Tempo / Langfuse / Arize. Use them
+ * to mark lifecycle moments the span attributes alone can't express:
+ *
+ *   - When the prompt was sent (vs. when the first token arrived)
+ *   - When each retry attempt started, and why
+ *   - When a streaming response produced its first token (TTFT)
+ *   - When a tool was invoked
+ *
+ * Every helper pins the event name + attribute keys to the published
+ * spec so downstream tooling (autotel-mcp, Langfuse, vendor UIs) can
+ * render them consistently.
+ *
+ * @example
+ * ```typescript
+ * import { trace, recordPromptSent, recordResponseReceived, recordRetry } from 'autotel';
+ *
+ * export const chat = trace('chat', ctx => async (prompt: string) => {
+ *   recordPromptSent(ctx, { model: 'gpt-4o', messageCount: 1 });
+ *
+ *   for (let attempt = 1; attempt <= 3; attempt++) {
+ *     try {
+ *       const res = await openai.chat.completions.create({...});
+ *       recordResponseReceived(ctx, {
+ *         model: res.model,
+ *         promptTokens: res.usage?.prompt_tokens,
+ *         completionTokens: res.usage?.completion_tokens,
+ *         finishReasons: res.choices.map(c => c.finish_reason),
+ *       });
+ *       return res;
+ *     } catch (err) {
+ *       recordRetry(ctx, { attempt, reason: 'rate_limit', delayMs: 500 });
+ *       await sleep(500 * attempt);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+
+/** Attributes expected on a `gen_ai.prompt.sent` event. */
+interface PromptSentEvent {
+    /** Model the caller intends to invoke (may differ from response model). */
+    model?: string;
+    /** Estimated input token count, when known before the call. */
+    promptTokens?: number;
+    /** Number of messages in a chat request (system + user + assistant). */
+    messageCount?: number;
+    /** Free-form operation kind — `chat` / `completion` / `embedding`. */
+    operation?: string;
+}
+/** Attributes expected on a `gen_ai.response.received` event. */
+interface ResponseReceivedEvent {
+    /** Model the provider actually served (may be more specific than requested). */
+    model?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    /** `stop`, `length`, `content_filter`, `tool_calls`, etc. */
+    finishReasons?: string[];
+}
+/** Attributes expected on a `gen_ai.retry` event. */
+interface RetryEvent {
+    attempt: number;
+    /** `rate_limit` | `timeout` | `provider_error` | custom label. */
+    reason?: string;
+    /** How long we'll wait before the next attempt. */
+    delayMs?: number;
+    /** HTTP status that triggered the retry, when applicable. */
+    statusCode?: number;
+}
+/** Attributes expected on a `gen_ai.tool.call` event. */
+interface ToolCallEvent {
+    toolName: string;
+    /** Call identifier so responses can be correlated back to calls. */
+    toolCallId?: string;
+    /** Pre-serialised tool arguments; omit if sensitive. */
+    arguments?: string;
+}
+/** Attributes expected on a `gen_ai.stream.first_token` event. */
+interface StreamFirstTokenEvent {
+    /** Tokens streamed so far, if the caller tracks that. */
+    tokensSoFar?: number;
+}
+/**
+ * Record that a prompt was dispatched to the provider. Typically called
+ * before `await provider.chat.completions.create(...)`.
+ */
+declare function recordPromptSent(ctx: TraceContext, event?: PromptSentEvent): void;
+/**
+ * Record a successful provider response. Call after the response arrives
+ * (for non-streaming) or after the stream completes.
+ */
+declare function recordResponseReceived(ctx: TraceContext, event?: ResponseReceivedEvent): void;
+/**
+ * Record a retry attempt on an LLM call. Call *before* sleeping for
+ * `delayMs` so the event timestamp accurately marks when the retry
+ * decision was made.
+ */
+declare function recordRetry(ctx: TraceContext, event: RetryEvent): void;
+/**
+ * Record a tool / function call made in the course of an agent step.
+ * Emits an event rather than a child span because many frameworks fire
+ * several tool calls within a single provider response.
+ */
+declare function recordToolCall(ctx: TraceContext, event: ToolCallEvent): void;
+/**
+ * Record the time-to-first-token for a streaming response. Pair with
+ * `recordResponseReceived` at the end so the span carries both the TTFT
+ * marker and the final usage numbers.
+ */
+declare function recordStreamFirstToken(ctx: TraceContext, event?: StreamFirstTokenEvent): void;
+
+export { AttributeRedactorConfig, AttributeRedactorPreset, BaggageSpanProcessor, type BaggageSpanProcessorOptions, EventAttributes, EventSubscriber, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, type OperationContext, type PromptSentEvent, type RequestLogSnapshot, type RequestLogger, type RequestLoggerOptions, type ResponseReceivedEvent, type RetryEvent, type StreamFirstTokenEvent, type StringRedactor, type StructuredError, type StructuredErrorInput, type ToolCallEvent, TraceContext, createStringRedactor, createStructuredError, flattenToAttributes, flush, formatDuration, genAiMetricViews, getEventQueue, getOperationContext, getRequestLogger, getStructuredErrorAttributes, llmHistogramAdvice, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordStructuredError, recordToolCall, runInOperationContext, runWithRequestContext, shutdown, structuredErrorToJSON, toAttributeValue, track };

package/dist/index.js

@@ -1,45 +1,46 @@
 export { createDrainPipeline } from './chunk-KFOHQK7X.js';
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-RXFZKLRQ.js';
-export { attrs, autoRedactPII, dbClient, httpClient, httpServer, identify, mergeAttrs, mergeServiceResource, request, safeSetAttributes, setDevice, setError, setException, setSession, setUser, validateAttribute } from './chunk-M4US3P4K.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-YN7USLHW.js';
+export { attrs, autoRedactPII, dbClient, httpClient, httpServer, identify, mergeAttrs, mergeServiceResource, request, safeSetAttributes, setDevice, setError, setException, setSession, setUser, validateAttribute } from './chunk-ER43K7ES.js';
 export { httpRequestHeaderAttribute, httpResponseHeaderAttribute } from './chunk-7552UTQW.js';
 export { HTTPAttributes, ServiceAttributes, URLAttributes } from './chunk-4A53YIAX.js';
 export { parseError } from './chunk-J7VGRIAJ.js';
-export { traceConsumer, traceProducer } from './chunk-GTD3NXOS.js';
+export { traceConsumer, traceProducer } from './chunk-QC5MNKVF.js';
 export { BusinessBaggage, createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
 import { resetMetrics } from './chunk-7SAWIN74.js';
 export { Metric, getMetrics, resetMetrics } from './chunk-7SAWIN74.js';
 import './chunk-5ZN622AO.js';
 export { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from './chunk-TQ5UWA7S.js';
-export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-DGPUZ6TE.js';
-import { getEventQueue, resetEventQueue } from './chunk-4PTCDOZY.js';
-export { ctx, getEventQueue, instrument, span, trace, track, withBaggage, withNewContext, withTracing } from './chunk-4PTCDOZY.js';
+export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-U54FTVFH.js';
+import { getEventQueue, resetEventQueue } from './chunk-HPUGKUMZ.js';
+export { ctx, getEventQueue, instrument, span, trace, track, withBaggage, withNewContext, withTracing } from './chunk-HPUGKUMZ.js';
 export { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, resolveTraceUrl, runWithSpan } from './chunk-B3ZHLLMP.js';
-import { resetEvents } from './chunk-WAB4CHBU.js';
-export { Event, getEvents, resetEvents } from './chunk-WAB4CHBU.js';
+import { resetEvents } from './chunk-BJ2XPN77.js';
+export { Event, getEvents, resetEvents } from './chunk-BJ2XPN77.js';
 import './chunk-LITNXTTT.js';
 import './chunk-BZHG5IZ4.js';
 export { getOperationContext, runInOperationContext } from './chunk-WD4RP6IV.js';
 export { CORRELATION_ID_BAGGAGE_KEY, generateCorrelationId, getCorrelationId, getOrCreateCorrelationId, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage } from './chunk-S4OFEXLA.js';
 import { createTraceContext } from './chunk-BBBWDIYQ.js';
 export { defineBaggageSchema } from './chunk-BBBWDIYQ.js';
-import { getLogger, getSdk, _closeEmbeddedDevtools } from './chunk-EXOXDI5A.js';
-export { BaggageSpanProcessor, createStringRedactor, init } from './chunk-EXOXDI5A.js';
-import './chunk-RUD7KS4R.js';
-import './chunk-XDKK53OL.js';
+import { getLogger, getSdk, _closeEmbeddedDevtools } from './chunk-W35FVJBC.js';
+export { BaggageSpanProcessor, createStringRedactor, init, isLoggerLocked, lockLogger } from './chunk-W35FVJBC.js';
+import './chunk-3SDILILG.js';
+import './chunk-A4E5AQFK.js';
 export { FilteringSpanProcessor } from './chunk-WGWSHJ2N.js';
 export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizingProcessor } from './chunk-GYR5K654.js';
-export { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, createAttributeRedactor, createRedactedSpan } from './chunk-SNINLBEE.js';
+export { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, createAttributeRedactor, createRedactedSpan } from './chunk-TDNKIHKT.js';
 import './chunk-6UQRVUN3.js';
 export { formatDuration } from './chunk-3QXBFGKP.js';
 import './chunk-33WTKH7X.js';
-export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets } from './chunk-VYA6QDNA.js';
-import './chunk-B33XPEKY.js';
+export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets } from './chunk-DPSA4QLA.js';
+import './chunk-55ER2KD5.js';
 import './chunk-J5QENANM.js';
 export { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from './chunk-HA2WBOGQ.js';
 import './chunk-DGUM43GV.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { SpanStatusCode, trace } from '@opentelemetry/api';
 export { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, trace as otelTrace, propagation } from '@opentelemetry/api';
+import { AggregationType } from '@opentelemetry/sdk-metrics';
 
 // src/shutdown.ts
 async function flush(options) {
@@ -228,6 +229,7 @@ function flattenToAttributes(fields, prefix = "") {
 }
 
 // src/structured-error.ts
+var internalKey = /* @__PURE__ */ Symbol.for("autotel.error.internal");
 function createStructuredError(input) {
   const error = new Error(input.message, {
     cause: input.cause
@@ -239,6 +241,21 @@ function createStructuredError(input) {
   if (input.code !== void 0) error.code = input.code;
   if (input.status !== void 0) error.status = input.status;
   if (input.details !== void 0) error.details = input.details;
+  if (input.internal !== void 0) {
+    Object.defineProperty(error, internalKey, {
+      value: input.internal,
+      enumerable: false,
+      writable: false,
+      configurable: true
+    });
+  }
+  Object.defineProperty(error, "internal", {
+    get() {
+      return this[internalKey];
+    },
+    enumerable: false,
+    configurable: true
+  });
   error.toString = () => {
     const lines = [`${error.name}: ${error.message}`];
     if (error.why) lines.push(`  Why: ${error.why}`);
@@ -246,11 +263,34 @@ function createStructuredError(input) {
     if (error.link) lines.push(`  Link: ${error.link}`);
     if (error.code !== void 0) lines.push(`  Code: ${error.code}`);
     if (error.status !== void 0) lines.push(`  Status: ${error.status}`);
-    if (error.cause) lines.push(`  Caused by: ${error.cause}`);
+    if (error.cause) {
+      const cause = error.cause;
+      lines.push(`  Caused by: ${cause.name}: ${cause.message}`);
+    }
     return lines.join("\n");
   };
   return error;
 }
+function structuredErrorToJSON(error) {
+  const result = {
+    name: error.name,
+    message: error.message
+  };
+  if (error.status !== void 0) result.status = error.status;
+  if (error.why || error.fix || error.link) {
+    result.data = {
+      ...error.why && { why: error.why },
+      ...error.fix && { fix: error.fix },
+      ...error.link && { link: error.link }
+    };
+  }
+  if (error.code !== void 0) result.code = error.code;
+  if (error.details) result.details = error.details;
+  if (error.cause instanceof Error) {
+    result.cause = { name: error.cause.name, message: error.cause.message };
+  }
+  return result;
+}
 function getStructuredErrorAttributes(error) {
   const structured = error;
   const attributes = {
@@ -285,6 +325,29 @@ function recordStructuredError(ctx2, error) {
 }
 
 // src/request-logger.ts
+var POST_EMIT_FORK_HINT = "For intentional background work tied to this request, use log.fork('label', fn) when available.";
+function warnPostEmit(method, detail) {
+  console.warn(
+    `[autotel] ${method} called after the wide event was emitted \u2014 ${detail} This data will not appear in observability. ${POST_EMIT_FORK_HINT}`
+  );
+}
+function mergeInto(target, source) {
+  for (const key in source) {
+    const sourceVal = source[key];
+    if (sourceVal === void 0) continue;
+    const targetVal = target[key];
+    if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
+      mergeInto(
+        targetVal,
+        sourceVal
+      );
+    } else if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
+      target[key] = [...targetVal, ...sourceVal];
+    } else {
+      target[key] = sourceVal;
+    }
+  }
+}
 var requestContextStore = new AsyncLocalStorage();
 function runWithRequestContext(ctx2, fn) {
   return requestContextStore.run(ctx2, fn);
@@ -304,6 +367,8 @@ function resolveContext(ctx2) {
 function getRequestLogger(ctx2, options) {
   const activeContext = resolveContext(ctx2);
   let contextState = {};
+  let emitted = false;
+  let lastSnapshot = null;
   const addLogEvent = (level, message, fields) => {
     const attrs2 = fields ? flattenToAttributes(fields) : void 0;
     activeContext.addEvent(`log.${level}`, {
@@ -311,44 +376,51 @@ function getRequestLogger(ctx2, options) {
       ...attrs2
     });
   };
+  const sealCheck = (method, keys) => {
+    if (emitted) {
+      warnPostEmit(
+        method,
+        `Keys dropped: ${keys.length ? keys.join(", ") : "(empty)"}.`
+      );
+    }
+  };
   return {
     set(fields) {
-      contextState = {
-        ...contextState,
-        ...fields
-      };
+      sealCheck("log.set()", Object.keys(fields));
+      if (emitted) return;
+      mergeInto(contextState, fields);
       activeContext.setAttributes(flattenToAttributes(fields));
     },
     info(message, fields) {
+      const keys = fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"];
+      sealCheck("log.info()", keys);
+      if (emitted) return;
       addLogEvent("info", message, fields);
       if (fields) {
-        contextState = {
-          ...contextState,
-          ...fields
-        };
+        mergeInto(contextState, fields);
         activeContext.setAttributes(flattenToAttributes(fields));
       }
     },
     warn(message, fields) {
+      const keys = fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"];
+      sealCheck("log.warn()", keys);
+      if (emitted) return;
       addLogEvent("warn", message, fields);
       activeContext.setAttribute("autotel.log.level", "warn");
       if (fields) {
-        contextState = {
-          ...contextState,
-          ...fields
-        };
+        mergeInto(contextState, fields);
         activeContext.setAttributes(flattenToAttributes(fields));
       }
     },
     error(error, fields) {
+      const keys = fields ? [...Object.keys(fields), "error"] : ["error"];
+      sealCheck("log.error()", keys);
+      if (emitted) return;
       const err = typeof error === "string" ? new Error(error) : error;
       recordStructuredError(activeContext, err);
       addLogEvent("error", err.message, fields);
       if (fields) {
-        contextState = {
-          ...contextState,
-          ...fields
-        };
+        mergeInto(contextState, fields);
         activeContext.setAttributes(flattenToAttributes(fields));
       }
       activeContext.setAttribute("autotel.log.level", "error");
@@ -357,6 +429,10 @@ function getRequestLogger(ctx2, options) {
       return { ...contextState };
     },
     emitNow(overrides) {
+      if (emitted) {
+        warnPostEmit("log.emitNow()", "Ignoring duplicate emit.");
+        return lastSnapshot;
+      }
       const mergedContext = {
         ...contextState,
         ...overrides ?? {}
@@ -378,11 +454,159 @@ function getRequestLogger(ctx2, options) {
           console.warn("[autotel] request logger onEmit failed:", error);
         });
       }
+      emitted = true;
+      lastSnapshot = snapshot;
       return snapshot;
+    },
+    fork(label, fn) {
+      const parentRequestId = activeContext.correlationId;
+      if (typeof parentRequestId !== "string" || parentRequestId.length === 0) {
+        throw new Error(
+          "[autotel] log.fork() requires the parent logger to have a correlationId. Ensure the request was created by autotel middleware."
+        );
+      }
+      const tracer = trace.getTracer("autotel.request-logger");
+      void tracer.startActiveSpan(`request.fork:${label}`, (childSpan) => {
+        const childContext = {
+          ...createTraceContext(childSpan),
+          correlationId: crypto.randomUUID()
+        };
+        requestContextStore.run(childContext, () => {
+          const childLog = getRequestLogger(childContext);
+          childLog.set({
+            operation: label,
+            _parentCorrelationId: parentRequestId
+          });
+          void Promise.resolve().then(() => fn()).then(() => {
+            childLog.emitNow();
+          }).catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            childLog.error(error);
+            childLog.emitNow();
+          }).finally(() => {
+            childSpan.end();
+          });
+        });
+      });
     }
   };
 }
+var GEN_AI_DURATION_BUCKETS_SECONDS = Object.freeze(
+  [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300]
+);
+var GEN_AI_TOKEN_USAGE_BUCKETS = Object.freeze([
+  1,
+  4,
+  16,
+  64,
+  256,
+  1024,
+  4096,
+  16384,
+  65536,
+  262144,
+  1048576,
+  4194304
+]);
+var GEN_AI_COST_USD_BUCKETS = Object.freeze([
+  1e-5,
+  1e-4,
+  1e-3,
+  5e-3,
+  0.01,
+  0.05,
+  0.1,
+  0.5,
+  1,
+  5,
+  10,
+  50
+]);
+function llmHistogramAdvice(kind) {
+  const boundaries = kind === "duration" ? GEN_AI_DURATION_BUCKETS_SECONDS : kind === "tokens" ? GEN_AI_TOKEN_USAGE_BUCKETS : GEN_AI_COST_USD_BUCKETS;
+  return { advice: { explicitBucketBoundaries: [...boundaries] } };
+}
+function genAiMetricViews(extra = []) {
+  const defaults = [
+    { instrumentName: "gen_ai.client.operation.duration", kind: "duration" },
+    { instrumentName: "gen_ai.client.token.usage", kind: "tokens" },
+    // Autotel-emitted cost metric. No-op if you don't emit it.
+    { instrumentName: "gen_ai.client.cost.usd", kind: "cost" }
+  ];
+  return [...defaults, ...extra].map(
+    ({ instrumentName, kind }) => ({
+      instrumentName,
+      aggregation: {
+        type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+        options: {
+          boundaries: kind === "duration" ? [...GEN_AI_DURATION_BUCKETS_SECONDS] : kind === "tokens" ? [...GEN_AI_TOKEN_USAGE_BUCKETS] : [...GEN_AI_COST_USD_BUCKETS]
+        }
+      }
+    })
+  );
+}
+
+// src/gen-ai-events.ts
+function recordPromptSent(ctx2, event = {}) {
+  ctx2.addEvent("gen_ai.prompt.sent", buildPromptSentAttrs(event));
+}
+function recordResponseReceived(ctx2, event = {}) {
+  ctx2.addEvent("gen_ai.response.received", buildResponseAttrs(event));
+}
+function recordRetry(ctx2, event) {
+  ctx2.addEvent("gen_ai.retry", buildRetryAttrs(event));
+}
+function recordToolCall(ctx2, event) {
+  ctx2.addEvent("gen_ai.tool.call", buildToolCallAttrs(event));
+}
+function recordStreamFirstToken(ctx2, event = {}) {
+  ctx2.addEvent("gen_ai.stream.first_token", buildStreamFirstTokenAttrs(event));
+}
+function buildPromptSentAttrs(event) {
+  const attrs2 = {};
+  if (event.model) attrs2["gen_ai.request.model"] = event.model;
+  if (event.promptTokens !== void 0)
+    attrs2["gen_ai.usage.input_tokens"] = event.promptTokens;
+  if (event.messageCount !== void 0)
+    attrs2["gen_ai.request.message_count"] = event.messageCount;
+  if (event.operation) attrs2["gen_ai.operation.name"] = event.operation;
+  return attrs2;
+}
+function buildResponseAttrs(event) {
+  const attrs2 = {};
+  if (event.model) attrs2["gen_ai.response.model"] = event.model;
+  if (event.promptTokens !== void 0)
+    attrs2["gen_ai.usage.input_tokens"] = event.promptTokens;
+  if (event.completionTokens !== void 0)
+    attrs2["gen_ai.usage.output_tokens"] = event.completionTokens;
+  if (event.totalTokens !== void 0)
+    attrs2["gen_ai.usage.total_tokens"] = event.totalTokens;
+  if (event.finishReasons && event.finishReasons.length > 0) {
+    attrs2["gen_ai.response.finish_reasons"] = event.finishReasons.join(",");
+  }
+  return attrs2;
+}
+function buildRetryAttrs(event) {
+  const attrs2 = { "retry.attempt": event.attempt };
+  if (event.reason) attrs2["retry.reason"] = event.reason;
+  if (event.delayMs !== void 0) attrs2["retry.delay_ms"] = event.delayMs;
+  if (event.statusCode !== void 0)
+    attrs2["http.response.status_code"] = event.statusCode;
+  return attrs2;
+}
+function buildToolCallAttrs(event) {
+  const attrs2 = { "gen_ai.tool.name": event.toolName };
+  if (event.toolCallId) attrs2["gen_ai.tool.call.id"] = event.toolCallId;
+  if (event.arguments) attrs2["gen_ai.tool.arguments"] = event.arguments;
+  return attrs2;
+}
+function buildStreamFirstTokenAttrs(event) {
+  const attrs2 = {};
+  if (event.tokensSoFar !== void 0)
+    attrs2["gen_ai.stream.tokens_so_far"] = event.tokensSoFar;
+  return attrs2;
+}
 
-export { createStructuredError, flattenToAttributes, flush, getRequestLogger, getStructuredErrorAttributes, recordStructuredError, runWithRequestContext, shutdown, toAttributeValue };
+export { GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, createStructuredError, flattenToAttributes, flush, genAiMetricViews, getRequestLogger, getStructuredErrorAttributes, llmHistogramAdvice, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordStructuredError, recordToolCall, runWithRequestContext, shutdown, structuredErrorToJSON, toAttributeValue };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map