import { type Span } from "#compiled/@opentelemetry/api/index.js"; /** Inputs for {@link traceChannelRequest}. */ export interface TraceChannelRequestInput { readonly request: Request; readonly routeKey: string; } /** * Wraps one inbound channel HTTP request in an OTel `SERVER` span. * * The span is named for the low-cardinality registered `routeKey` * (`"POST /eve/v1/session/:sessionId"`), never the concrete URL, while the * `http.route` attribute carries only the path template — the OTel HTTP * semantic convention reserves `http.route` for the route template alone, * with the method in `http.request.method`. The span is started from the * context extracted off the incoming request headers so an upstream * `traceparent` becomes its parent and nested channel and Workflow spans * (`hook.resume` and outgoing HTTP) become its descendants. * * The handler runs inside the span's active context. When it returns, the * response status is recorded and a `>= 500` status marks the span as an * error. A thrown handler is recorded once and rethrown — handler * exceptions that eve already converts to a JSON 500 return normally and * are recorded by `logError` against this active span, so they are not * recorded a second time here. The span always ends in `finally`, without * waiting for `event.waitUntil()` work or streamed response bodies. * * Emitting these spans is opt-in: unless authored instrumentation enables it * via `defineInstrumentation({ traceChannelRequests: true })`, the handler runs * with no span (`undefined`) and no context extraction — a true bypass, not a * non-recording span. * * This is observability-only: it never changes the response and performs no * synchronous span export in the request path, adding only minimal in-process * tracing overhead. */ export declare function traceChannelRequest(input: TraceChannelRequestInput, handler: (span: Span | undefined) => Promise): Promise;