import { type Span } from '@opentelemetry/api';
/**
 * Field on an outgoing WS frame that carries the W3C trace context. Chosen as a
 * dedicated, namespaced top-level key (rather than overloading per-event fields)
 * so the gateway can read it generically off ANY client event with one check,
 * regardless of the event `type`. Double-underscore signals "transport metadata,
 * not protocol payload" — gateway handlers that don't know about it simply ignore
 * the extra key (JSON is forward-compatible).
 *
 * Carrier shape: `{ traceparent: string, tracestate?: string }` per the W3C
 * Trace Context spec (https://www.w3.org/TR/trace-context/).
 */
export declare const OTEL_CARRIER_KEY: "__otel";
export interface SpanIdentity {
    /** End-user id (maps to OTel `enduser.id`). */
    userId?: string | null;
    /** Gateway session id (maps to `session.id`). */
    sessionId?: string | null;
}
/**
 * Start a CLIENT span for a discrete GatewayClient operation (e.g. `connect`,
 * `send message`). Returns the span; caller MUST call `endSpan(span)` (or
 * `failSpan`) — `runWithSpan` does this automatically for sync work.
 *
 * No-op SDK → returns a no-op span; all methods are safe to call and do nothing.
 */
export declare function startClientSpan(name: string, identity: SpanIdentity, extraAttributes?: Record<string, string | number | boolean>): Span;
/**
 * The currently-active span on the context, or null when none (or no SDK).
 * Used to propagate context onto non-message control frames without opening a
 * dedicated span.
 */
export declare function getActiveSpan(): Span | null;
/** End a span successfully. Safe on a no-op span. */
export declare function endSpan(span: Span): void;
/** Record an error on a span and end it. Safe on a no-op span. */
export declare function failSpan(span: Span, err: unknown): void;
/**
 * Inject the W3C trace context for `span` into a fresh carrier object and return
 * it. The carrier is `{ traceparent, tracestate? }`. When no SDK is installed the
 * propagator is a no-op and the returned carrier is empty `{}` — callers should
 * therefore only attach it when it actually has keys (see `attachTraceContext`).
 */
export declare function injectTraceContext(span: Span): Record<string, string>;
/**
 * Returns `event` unchanged when there's no trace context to inject (no active
 * SDK), or a shallow copy with the `__otel` carrier added when there is. Never
 * mutates the input. Generic over the event shape so it composes with the
 * protocol's `ClientEvent` union without widening it at the call site.
 */
export declare function attachTraceContext<T extends object>(event: T, span: Span): T;
//# sourceMappingURL=otel.d.ts.map