autotel/dist/correlation-id.d.cts

Write Once, Observe Anywhere

import * as _opentelemetry_api from '@opentelemetry/api';
import { AsyncLocalStorage } from 'node:async_hooks';

type CorrelationStore = {
    value: string;
};
/**
 * Baggage key for correlation ID propagation
 */
declare const CORRELATION_ID_BAGGAGE_KEY = "autotel.correlation_id";
/**
 * Generate a new correlation ID
 *
 * Format: 16 hex chars (64 bits), crypto-random, URL-safe
 *
 * @returns A new correlation ID
 *
 * @example
 * ```typescript
 * const id = generateCorrelationId();
 * // Returns: 'a1b2c3d4e5f67890'
 * ```
 */
declare function generateCorrelationId(): string;
/**
 * Get the current correlation ID from context
 *
 * Resolution order:
 * 1. AsyncLocalStorage (from explicit setCorrelationId or runWithCorrelationId)
 * 2. Baggage (if propagated from upstream)
 * 3. Active span's trace ID (first 16 chars as fallback)
 * 4. undefined (if not in any context)
 *
 * @returns Current correlation ID or undefined
 *
 * @example
 * ```typescript
 * const id = getCorrelationId();
 * if (id) {
 *   console.log('Correlation ID:', id);
 * }
 * ```
 */
declare function getCorrelationId(): string | undefined;
/**
 * Get or create a correlation ID
 *
 * If a correlation ID exists in the current context, returns it.
 * Otherwise, generates a new one.
 *
 * @returns Existing or new correlation ID
 *
 * @example
 * ```typescript
 * const id = getOrCreateCorrelationId();
 * // Always returns a valid correlation ID
 * ```
 */
declare function getOrCreateCorrelationId(): string;
/**
 * Run a function with a specific correlation ID in context
 *
 * The correlation ID will be available via getCorrelationId() throughout
 * the execution of the function and any async operations it spawns.
 *
 * @param correlationId - Correlation ID to use
 * @param fn - Function to execute
 * @returns The return value of the function
 *
 * @example
 * ```typescript
 * await runWithCorrelationId('abc123', async () => {
 *   // getCorrelationId() returns 'abc123' here
 *   await processRequest();
 * });
 * ```
 */
declare function runWithCorrelationId<T>(correlationId: string, fn: () => T): T;
/**
 * Set correlation ID in the current context (mutates context)
 *
 * Note: This updates the AsyncLocalStorage context. For proper scoping
 * across async boundaries, prefer runWithCorrelationId() instead.
 *
 * @param correlationId - Correlation ID to set
 *
 * @example
 * ```typescript
 * setCorrelationId('abc123');
 * // Now getCorrelationId() returns 'abc123'
 * ```
 */
declare function setCorrelationId(correlationId: string): void;
/**
 * Set correlation ID in baggage for propagation
 *
 * This adds the correlation ID to the W3C baggage header, allowing it
 * to be propagated to downstream services.
 *
 * Note: Only use this when you explicitly want cross-service propagation.
 * Default is OFF to avoid header bloat.
 *
 * @param correlationId - Correlation ID to propagate
 * @returns New context with baggage set
 *
 * @example
 * ```typescript
 * const newContext = setCorrelationIdInBaggage('abc123');
 * context.with(newContext, () => {
 *   // Baggage will be propagated in outgoing requests
 * });
 * ```
 */
declare function setCorrelationIdInBaggage(correlationId: string): _opentelemetry_api.Context;
/**
 * Get the correlation storage instance (for internal use in init/shutdown)
 */
declare function getCorrelationStorage(): AsyncLocalStorage<CorrelationStore>;

export { CORRELATION_ID_BAGGAGE_KEY, generateCorrelationId, getCorrelationId, getCorrelationStorage, getOrCreateCorrelationId, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage };