/**
 * Trace context following W3C specification
 */
export interface TraceContext {
    /** 16-byte trace ID as 32 hex characters */
    traceId: string;
    /** 8-byte span ID as 16 hex characters */
    spanId: string;
    /** Parent span ID (for nested spans) */
    parentSpanId?: string;
    /** Trace flags (sampled = 01, not sampled = 00) */
    traceFlags: string;
    /** Full traceparent header value */
    traceparent: string;
    /** Optional tracestate header for vendor-specific data */
    tracestate?: string;
}
/**
 * Trace span for timing and hierarchy
 */
export interface TraceSpan {
    /** Span name/operation */
    name: string;
    /** Span ID */
    spanId: string;
    /** Parent span ID */
    parentSpanId?: string;
    /** Start timestamp */
    startTime: number;
    /** End timestamp (set when span ends) */
    endTime?: number;
    /** Span attributes */
    attributes: Record<string, unknown>;
    /** Span events (point-in-time occurrences) */
    events: Array<{
        name: string;
        timestamp: number;
        attributes?: Record<string, unknown>;
    }>;
    /** Span status */
    status: 'unset' | 'ok' | 'error';
    /** Error message if status is error */
    errorMessage?: string;
}
/**
 * Generate a 16-byte trace ID (32 hex characters)
 */
export declare function generateTraceId(): string;
/**
 * Generate an 8-byte span ID (16 hex characters)
 */
export declare function generateSpanId(): string;
/**
 * Build traceparent header value
 * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
 * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
 */
export declare function buildTraceparent(traceId: string, spanId: string, traceFlags?: string): string;
/**
 * Parse traceparent header value
 * Returns null if invalid
 */
export declare function parseTraceparent(header: string): {
    version: string;
    traceId: string;
    parentId: string;
    traceFlags: string;
} | null;
/**
 * Create a new trace context
 * Optionally continue from an existing traceparent header
 */
export declare function createTraceContext(existingTraceparent?: string): TraceContext;
/**
 * Get the current trace context from async local storage
 */
export declare function getTraceContext(): TraceContext | undefined;
/**
 * Run a function with a specific trace context
 */
export declare function runWithTraceContext<T>(context: TraceContext, fn: () => T): T;
/**
 * Run a function with a new trace context (continuing from optional parent)
 */
export declare function runInNewTrace<T>(fn: () => T, existingTraceparent?: string): T;
/**
 * Create a child span ID in the current trace
 * Returns a new span ID while preserving the trace ID
 */
export declare function createChildSpanId(): string;
/**
 * Get trace context for logging
 * Returns object suitable for including in log entries
 */
export declare function getTraceLogContext(): Record<string, string> | undefined;
/**
 * Extract trace context from HTTP headers
 */
export declare function extractTraceFromHeaders(headers: Record<string, string | string[] | undefined>): TraceContext | null;
/**
 * Inject trace context into HTTP headers
 */
export declare function injectTraceToHeaders(headers: Record<string, string>, context?: TraceContext): Record<string, string>;
/**
 * Start a new span within the current trace
 */
export declare function startSpan(name: string, attributes?: Record<string, unknown>): TraceSpan;
/**
 * End a span
 */
export declare function endSpan(span: TraceSpan, status?: 'ok' | 'error', errorMessage?: string): void;
/**
 * Add an event to a span
 */
export declare function addSpanEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
/**
 * Set span attribute
 */
export declare function setSpanAttribute(span: TraceSpan, key: string, value: unknown): void;
/**
 * Run a function within a span
 */
export declare function withSpan<T>(name: string, fn: (span: TraceSpan) => Promise<T>, attributes?: Record<string, unknown>): Promise<T>;
/**
 * Serialize trace context for queue job data
 */
export declare function serializeTraceContext(context?: TraceContext): string | undefined;
/**
 * Deserialize trace context from queue job data
 */
export declare function deserializeTraceContext(data: string | undefined): TraceContext | null;
/**
 * Propagate trace context for BullMQ jobs
 * Add trace context to job data
 */
export declare function addTraceToJobData<T extends Record<string, unknown>>(data: T, context?: TraceContext): T & {
    _trace?: string;
};
/**
 * Extract trace context from BullMQ job data
 */
export declare function extractTraceFromJobData(data: Record<string, unknown>): TraceContext | null;
//# sourceMappingURL=trace.d.ts.map