/**
 * @fileoverview Helpers for working with trace context across boundaries.
 * Provides utilities for W3C traceparent headers, distributed tracing,
 * custom span creation, and context propagation across async boundaries.
 * @module src/utils/telemetry/trace
 */
import { type Span } from '@opentelemetry/api';
import type { RequestContext } from '../../utils/internal/requestContext.js';
/**
 * Parsed fields from a W3C `traceparent` header (`00-<traceId>-<spanId>-<flags>`).
 * Used to propagate distributed trace context across service boundaries.
 * @see https://www.w3.org/TR/trace-context/
 */
export interface TraceparentInfo {
    /** Whether the trace is sampled (flags byte `01` = sampled, `00` = not sampled). */
    sampled: boolean;
    /** W3C parent span ID — 16 lowercase hex characters identifying the caller's span. */
    spanId: string;
    /** W3C trace ID — 32 lowercase hex characters shared across the entire distributed trace. */
    traceId: string;
}
/**
 * Builds a W3C `traceparent` header value from a `RequestContext` or the currently active span.
 * Uses `ctx.traceId`/`ctx.spanId` when provided; falls back to the active OTel span context.
 * The version field is always `00` and the flags byte is hardcoded to `01` (sampled).
 * Returns `undefined` when neither source yields a trace ID and span ID.
 *
 * @param ctx - Optional RequestContext containing `traceId` and `spanId`
 * @returns Formatted `traceparent` string (e.g., `00-<traceId>-<spanId>-01`), or `undefined`
 *
 * @example
 * ```typescript
 * const traceparent = buildTraceparent(requestContext);
 * if (traceparent) {
 *   fetch(url, { headers: { traceparent } });
 * }
 * ```
 */
export declare function buildTraceparent(ctx?: RequestContext): string | undefined;
/**
 * Extracts W3C traceparent from headers and returns parsed trace/span IDs.
 * Returns undefined if header is missing or malformed.
 *
 * @param headers - Headers object (Web API Headers or plain object)
 * @returns Parsed traceparent info or undefined
 *
 * @example
 * ```typescript
 * // Extract trace context from incoming request
 * const trace = extractTraceparent(request.headers);
 * if (trace) {
 *   logger.info('Processing with parent trace', {
 *     traceId: trace.traceId,
 *     sampled: trace.sampled
 *   });
 * }
 * ```
 */
export declare function extractTraceparent(headers: Headers | Record<string, string | undefined>): TraceparentInfo | undefined;
/**
 * Creates a child RequestContext with parent trace context extracted from headers.
 * Useful for propagating trace context from incoming HTTP requests.
 *
 * @param parentHeaders - Headers containing traceparent
 * @param operation - Operation name for the new context
 * @returns New RequestContext with inherited trace context
 *
 * @example
 * ```typescript
 * // In HTTP handler
 * const context = createContextWithParentTrace(
 *   request.headers,
 *   'handleApiRequest'
 * );
 * logger.info('Processing request', context);
 * ```
 */
export declare function createContextWithParentTrace(parentHeaders: Headers | Record<string, string | undefined>, operation: string): RequestContext;
/**
 * Injects the current active context into a carrier, returning it.
 * Useful for HTTP headers: pass an object and use resulting key/values.
 *
 * @param carrier - Object to inject context into (typically headers)
 * @returns Same carrier with injected trace context
 *
 * @example
 * ```typescript
 * const headers = injectCurrentContextInto({
 *   'Content-Type': 'application/json'
 * });
 * // headers now contains traceparent, tracestate, etc.
 * ```
 */
export declare function injectCurrentContextInto<T extends Record<string, unknown>>(carrier: T): T;
/**
 * Creates a new span for manual instrumentation with automatic error handling.
 * The span is automatically marked as OK on success or ERROR on exception.
 * Errors are recorded as exceptions and automatically propagated.
 *
 * @param operationName - Name of the span (e.g., 'database.query', 'external.api')
 * @param fn - Async function to execute within the span
 * @param attributes - Optional attributes to attach to the span
 * @returns Promise resolving to the function's return value
 *
 * @example
 * ```typescript
 * // Instrument a database query
 * const users = await withSpan(
 *   'database.query.users',
 *   async () => db.users.findMany(),
 *   { 'db.table': 'users', 'db.operation': 'select' }
 * );
 * ```
 */
export declare function withSpan<T>(operationName: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
/**
 * Runs a function within the currently active OpenTelemetry context.
 * Useful for carrying the active context across async boundaries (e.g., `setTimeout`, `queueMicrotask`).
 *
 * **Limitation:** When `ctx` contains trace IDs, this function executes within the
 * current active context rather than restoring `ctx`'s specific span context.
 * Full span restoration would require span recreation, which this utility intentionally avoids.
 * If `ctx` has no trace IDs, `fn` is called directly without any context wrapping.
 *
 * @param ctx - RequestContext containing trace IDs; if missing or lacking IDs, `fn` runs directly
 * @param fn - Function to execute within the active OTel context
 * @returns Result of `fn`
 *
 * @example
 * ```typescript
 * // Carry the active OTel context into a setTimeout callback
 * const context = requestContextService.createRequestContext({ operation: 'delayed' });
 * setTimeout(() => {
 *   runInContext(context, () => {
 *     logger.info('Still in trace context', context);
 *   });
 * }, 1000);
 * ```
 */
export declare function runInContext<T>(ctx: RequestContext | undefined, fn: () => T): T;
//# sourceMappingURL=trace.d.ts.map