autotel 2.1.0

package/dist/trace-helpers.d.cts

@@ -0,0 +1,524 @@
+import { Tracer, Span, Context } from '@opentelemetry/api';
+
+/**
+ * Trace context helpers - Core primitives for trace correlation
+ *
+ * These are the building blocks that allow users to bring their own logger
+ * (bunyan, log4js, custom, etc.) and add trace correlation.
+ *
+ * @example Using with bunyan
+ * ```typescript
+ * import bunyan from 'bunyan';
+ * import { enrichWithTraceContext } from 'autotel/trace-helpers';
+ *
+ * const bunyanLogger = bunyan.createLogger({ name: 'myapp' });
+ *
+ * const logger = {
+ *   info: (msg: string, extra?: object) => {
+ *     bunyanLogger.info(enrichWithTraceContext(extra || {}), msg);
+ *   }
+ * };
+ * ```
+ *
+ * @example Using with log4js
+ * ```typescript
+ * import log4js from 'log4js';
+ * import { getTraceContext } from 'autotel/trace-helpers';
+ *
+ * const log4jsLogger = log4js.getLogger();
+ *
+ * function logWithTrace(level: string, msg: string, extra?: object) {
+ *   const context = getTraceContext();
+ *   log4jsLogger[level](msg, { ...extra, ...context });
+ * }
+ * ```
+ */
+
+/**
+ * Store span name for a given span
+ * Called internally when spans are created
+ */
+declare function setSpanName(span: Span, name: string): void;
+/**
+ * Trace context extracted from active span
+ */
+interface TraceContext {
+    /** Full 32-character hex trace ID */
+    traceId: string;
+    /** 16-character hex span ID */
+    spanId: string;
+    /** First 16 characters of trace ID (for log grouping/correlation) */
+    correlationId: string;
+    /** Function/operation name (OpenTelemetry semantic convention: code.function) */
+    'code.function'?: string;
+    /** Datadog trace ID in decimal format (lower 64 bits) for log-trace correlation */
+    'dd.trace_id'?: string;
+    /** Datadog span ID in decimal format for log-trace correlation */
+    'dd.span_id'?: string;
+}
+/**
+ * Get current trace context from active span
+ *
+ * Returns null if no span is active (e.g., outside of trace operation)
+ *
+ * Includes both OpenTelemetry standard fields (hex) and Datadog-specific
+ * fields (decimal) for maximum compatibility.
+ *
+ * @returns Trace context with traceId, spanId, correlationId, and Datadog decimal IDs, or null
+ *
+ * @example
+ * ```typescript
+ * import { getTraceContext } from 'autotel/trace-helpers';
+ *
+ * const context = getTraceContext();
+ * if (context) {
+ *   console.log('Current trace:', context.traceId);
+ *   // Current trace: 4bf92f3577b34da6a3ce929d0e0e4736
+ *   console.log('Datadog trace ID:', context['dd.trace_id']);
+ *   // Datadog trace ID: 12007117331170166582 (decimal for log correlation)
+ * }
+ * ```
+ */
+declare function getTraceContext(): TraceContext | null;
+/**
+ * Enrich object with trace context (traceId, spanId, correlationId, and Datadog fields)
+ *
+ * If no span is active, returns the object unchanged.
+ * This prevents "undefined" or "null" values in logs.
+ *
+ * Automatically adds both OpenTelemetry standard fields (hex) and Datadog-specific
+ * fields (decimal) for maximum compatibility with observability backends.
+ *
+ * @param obj - Object to enrich (e.g., log metadata)
+ * @returns Object with trace context merged in, or unchanged if no active span
+ *
+ * @example
+ * ```typescript
+ * import { enrichWithTraceContext } from 'autotel/trace-helpers';
+ *
+ * // Inside a trace operation:
+ * const enriched = enrichWithTraceContext({ userId: '123' });
+ * // {
+ * //   userId: '123',
+ * //   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+ * //   spanId: '00f067aa0ba902b7',
+ * //   correlationId: '4bf92f3577b34da6',
+ * //   'dd.trace_id': '12007117331170166582',  // Datadog decimal format
+ * //   'dd.span_id': '67667974448284583'       // Datadog decimal format
+ * // }
+ *
+ * // Outside trace operation:
+ * const unchanged = enrichWithTraceContext({ userId: '123' });
+ * // { userId: '123' } - no trace fields added
+ * ```
+ */
+declare function enrichWithTraceContext<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Check if currently in a trace context
+ *
+ * Useful for conditional logic based on trace presence
+ *
+ * @returns true if active span exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isTracing } from 'autotel/trace-helpers';
+ *
+ * if (isTracing()) {
+ *   // Add expensive debug metadata only when tracing
+ *   logger.debug('Detailed context', expensiveDebugData());
+ * }
+ * ```
+ */
+declare function isTracing(): boolean;
+/**
+ * Get a tracer instance for creating custom spans
+ *
+ * Use this when you need low-level control over span lifecycle.
+ * For most use cases, prefer trace(), span(), or instrument() instead.
+ *
+ * @param name - Tracer name (usually your service or module name)
+ * @param version - Optional version string
+ * @returns OpenTelemetry Tracer instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { getTracer } from 'autotel';
+ *
+ * const tracer = getTracer('my-service');
+ * const span = tracer.startSpan('custom.operation');
+ * try {
+ *   // Your logic
+ *   span.setAttribute('key', 'value');
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ *
+ * @example With AI SDK
+ * ```typescript
+ * import { getTracer } from 'autotel';
+ * import { generateText } from 'ai';
+ *
+ * const tracer = getTracer('ai-agent');
+ * const result = await generateText({
+ *   model: myModel,
+ *   prompt: 'Hello',
+ *   experimental_telemetry: {
+ *     isEnabled: true,
+ *     tracer,
+ *   },
+ * });
+ * ```
+ */
+declare function getTracer(name: string, version?: string): Tracer;
+/**
+ * Get the currently active span
+ *
+ * Returns undefined if no span is currently active.
+ * Useful for adding attributes or events to the current span.
+ *
+ * @returns Active span or undefined
+ *
+ * @example Adding attributes to active span
+ * ```typescript
+ * import { getActiveSpan } from 'autotel';
+ *
+ * const span = getActiveSpan();
+ * if (span) {
+ *   span.setAttribute('user.id', userId);
+ *   span.addEvent('User action', { action: 'click' });
+ * }
+ * ```
+ *
+ * @example Checking span status
+ * ```typescript
+ * import { getActiveSpan, SpanStatusCode } from 'autotel';
+ *
+ * const span = getActiveSpan();
+ * if (span?.isRecording()) {
+ *   span.setStatus({ code: SpanStatusCode.OK });
+ * }
+ * ```
+ */
+declare function getActiveSpan(): Span | undefined;
+/**
+ * Get the currently active OpenTelemetry context
+ *
+ * The context contains the active span and any baggage.
+ * Useful for context propagation and custom instrumentation.
+ *
+ * @returns Current active context
+ *
+ * @example Propagating context
+ * ```typescript
+ * import { getActiveContext } from 'autotel';
+ *
+ * const currentContext = getActiveContext();
+ * // Pass context to another function or service
+ * ```
+ *
+ * @example With context injection
+ * ```typescript
+ * import { getActiveContext, injectTraceContext } from 'autotel';
+ *
+ * const headers = {};
+ * injectTraceContext(headers);
+ * // Headers now contain trace propagation data
+ * ```
+ */
+declare function getActiveContext(): Context;
+/**
+ * Run a function with a specific span set as active
+ *
+ * This is a convenience wrapper around the two-step process of
+ * setting a span in context and running code within that context.
+ *
+ * @param span - The span to set as active
+ * @param fn - Function to execute with the span active
+ * @returns The return value of the function
+ *
+ * @example Running code with a custom span
+ * ```typescript
+ * import { getTracer, runWithSpan } from 'autotel';
+ *
+ * const tracer = getTracer('my-service');
+ * const span = tracer.startSpan('background.job');
+ *
+ * try {
+ *   const result = await runWithSpan(span, async () => {
+ *     // Any spans created here will be children of 'background.job'
+ *     await processData();
+ *     return { success: true };
+ *   });
+ *   console.log(result);
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ *
+ * @example Testing with custom spans
+ * ```typescript
+ * import { runWithSpan, otelTrace } from 'autotel';
+ *
+ * const tracer = otelTrace.getTracer('test');
+ * const span = tracer.startSpan('test.operation');
+ *
+ * const result = runWithSpan(span, () => {
+ *   // Code under test runs with this span as active
+ *   return myFunction();
+ * });
+ *
+ * span.end();
+ * ```
+ */
+declare function runWithSpan<T>(span: Span, fn: () => T): T;
+/**
+ * Finalize a span with appropriate status and optional error recording
+ *
+ * This is a convenience function that:
+ * - Records exceptions if an error is provided
+ * - Sets span status to ERROR if error exists, OK otherwise
+ * - Ends the span
+ *
+ * @param span - The span to finalize
+ * @param error - Optional error to record
+ *
+ * @example Without error (success case)
+ * ```typescript
+ * import { getTracer, finalizeSpan } from 'autotel';
+ *
+ * const tracer = getTracer('my-service');
+ * const span = tracer.startSpan('operation');
+ *
+ * try {
+ *   await doWork();
+ *   finalizeSpan(span);
+ * } catch (error) {
+ *   finalizeSpan(span, error);
+ *   throw error;
+ * }
+ * ```
+ *
+ * @example With error
+ * ```typescript
+ * import { getTracer, finalizeSpan } from 'autotel';
+ *
+ * const tracer = getTracer('my-service');
+ * const span = tracer.startSpan('operation');
+ *
+ * try {
+ *   await riskyOperation();
+ *   finalizeSpan(span);
+ * } catch (error) {
+ *   finalizeSpan(span, error); // Records exception and sets ERROR status
+ *   throw error;
+ * }
+ * ```
+ *
+ * @example In instrumentation
+ * ```typescript
+ * import { getTracer, runWithSpan, finalizeSpan } from 'autotel';
+ *
+ * function instrumentedQuery(query: string) {
+ *   const tracer = getTracer('db');
+ *   const span = tracer.startSpan('db.query');
+ *
+ *   return runWithSpan(span, () => {
+ *     try {
+ *       const result = executeQuery(query);
+ *       finalizeSpan(span);
+ *       return result;
+ *     } catch (error) {
+ *       finalizeSpan(span, error);
+ *       throw error;
+ *     }
+ *   });
+ * }
+ * ```
+ */
+declare function finalizeSpan(span: Span, error?: unknown): void;
+/**
+ * Creates a deterministic trace ID from a seed string.
+ *
+ * Generates a consistent 128-bit trace ID (32 hex characters) from an input seed
+ * using SHA-256 hashing. Useful for correlating external system IDs (request IDs,
+ * order IDs, session IDs) with OpenTelemetry trace IDs.
+ *
+ * **Use Cases:**
+ * - Correlate external request IDs with traces
+ * - Link customer support tickets to trace data
+ * - Associate business entities (orders, sessions) with observability data
+ * - Debug specific user flows by deterministic trace lookup
+ *
+ * **Important:** Only use this when you need deterministic trace IDs for correlation.
+ * For normal tracing, let OpenTelemetry generate random trace IDs automatically.
+ *
+ * **Runtime Support:**
+ * - Node.js 15+ (native crypto.subtle)
+ * - All modern browsers
+ * - Edge runtimes (Cloudflare Workers, Deno, etc.)
+ *
+ * @param seed - Input string to generate trace ID from (e.g., request ID, order ID)
+ * @returns Promise resolving to a 32-character hex trace ID (128 bits)
+ *
+ * @example Correlate external request ID with trace
+ * ```typescript
+ * import { createDeterministicTraceId } from 'autotel/trace-helpers'
+ * import { trace, context } from '@opentelemetry/api'
+ *
+ * // In middleware or request handler
+ * const requestId = req.headers['x-request-id']
+ * const traceId = await createDeterministicTraceId(requestId)
+ *
+ * // Use with manual span creation (advanced - not needed with trace/span functions)
+ * const tracer = trace.getTracer('my-service')
+ * const spanContext = {
+ *   traceId,
+ *   spanId: '0123456789abcdef', // Still random
+ *   traceFlags: 1
+ * }
+ * ```
+ *
+ * @example Link customer support tickets to traces
+ * ```typescript
+ * import { createDeterministicTraceId } from 'autotel/trace-helpers'
+ *
+ * // Support dashboard integration
+ * const ticketId = 'TICKET-12345'
+ * const traceId = await createDeterministicTraceId(ticketId)
+ *
+ * // Generate direct link to traces in observability backend
+ * const traceUrl = `https://your-otel-backend.com/traces/${traceId}`
+ * console.log(`View related traces: ${traceUrl}`)
+ * ```
+ *
+ * @example Session-based correlation
+ * ```typescript
+ * import { createDeterministicTraceId } from 'autotel/trace-helpers'
+ *
+ * // Track all operations for a user session
+ * const sessionId = req.session.id
+ * const traceId = await createDeterministicTraceId(sessionId)
+ *
+ * // All operations in this session share the same trace ID
+ * // Makes it easy to find all activity for a specific session
+ * ```
+ *
+ * @public
+ */
+declare function createDeterministicTraceId(seed: string): Promise<string>;
+/**
+ * Flattens nested metadata objects into dot-notation span attributes.
+ *
+ * Converts complex nested objects into flat key-value pairs suitable for
+ * OpenTelemetry span attributes. Non-string values are JSON serialized.
+ * Handles serialization failures gracefully with a fallback value.
+ *
+ * **Use Cases:**
+ * - Structured metadata with nested objects
+ * - User context with multiple properties
+ * - Request/response metadata
+ * - Business entity attributes
+ *
+ * **Note:** Filters out null/undefined values automatically to keep spans clean.
+ *
+ * @param metadata - Nested metadata object to flatten
+ * @param prefix - Prefix for all attribute keys (default: 'metadata')
+ * @returns Flattened attributes as { [key: string]: string }
+ *
+ * @example Basic metadata flattening
+ * ```typescript
+ * import { flattenMetadata } from 'autotel/trace-helpers'
+ * import { trace } from 'autotel'
+ *
+ * export const processOrder = trace(ctx => async (orderId: string) => {
+ *   const order = await getOrder(orderId)
+ *
+ *   // Flatten complex order metadata
+ *   const flattened = flattenMetadata({
+ *     user: { id: order.userId, tier: 'premium' },
+ *     payment: { method: 'card', processor: 'stripe' },
+ *     items: order.items.length
+ *   })
+ *
+ *   ctx.setAttributes(flattened)
+ *   // Results in:
+ *   // {
+ *   //   'metadata.user.id': 'user-123',
+ *   //   'metadata.user.tier': 'premium',
+ *   //   'metadata.payment.method': 'card',
+ *   //   'metadata.payment.processor': 'stripe',
+ *   //   'metadata.items': '5'
+ *   // }
+ * })
+ * ```
+ *
+ * @example Custom prefix for semantic conventions
+ * ```typescript
+ * import { flattenMetadata } from 'autotel/trace-helpers'
+ * import { trace } from 'autotel'
+ *
+ * export const fetchUser = trace(ctx => async (userId: string) => {
+ *   const user = await db.users.findOne({ id: userId })
+ *
+ *   // Use semantic convention prefix
+ *   const userAttrs = flattenMetadata(
+ *     {
+ *       id: user.id,
+ *       email: user.email,
+ *       plan: user.subscription.plan
+ *     },
+ *     'user'  // Custom prefix
+ *   )
+ *
+ *   ctx.setAttributes(userAttrs)
+ *   // Results in:
+ *   // {
+ *   //   'user.id': 'user-123',
+ *   //   'user.email': 'user@example.com',
+ *   //   'user.plan': 'enterprise'
+ *   // }
+ * })
+ * ```
+ *
+ * @example With complex objects (auto-serialized)
+ * ```typescript
+ * import { flattenMetadata } from 'autotel/trace-helpers'
+ * import { trace } from 'autotel'
+ *
+ * export const analyzeRequest = trace(ctx => async (req: Request) => {
+ *   const metadata = flattenMetadata({
+ *     headers: req.headers,  // Object - will be JSON serialized
+ *     query: req.query,       // Object - will be JSON serialized
+ *     timestamp: new Date()   // Non-string - will be JSON serialized
+ *   })
+ *
+ *   ctx.setAttributes(metadata)
+ *   // Results in:
+ *   // {
+ *   //   'metadata.headers': '{"accept":"application/json",...}',
+ *   //   'metadata.query': '{"page":"1","limit":"10"}',
+ *   //   'metadata.timestamp': '"2024-01-15T12:00:00.000Z"'
+ *   // }
+ * })
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { flattenMetadata } from 'autotel/trace-helpers'
+ *
+ * // Objects with circular references are handled gracefully
+ * const circular: any = { a: 1 }
+ * circular.self = circular
+ *
+ * const flattened = flattenMetadata({ data: circular })
+ * // Results in:
+ * // { 'metadata.data': '<serialization-failed>' }
+ * ```
+ *
+ * @public
+ */
+declare function flattenMetadata(metadata: Record<string, unknown>, prefix?: string): Record<string, string>;
+
+export { type TraceContext, createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, runWithSpan, setSpanName };