eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
33 lines (32 loc) • 1.75 kB
TypeScript
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 and
* `http.request.method` carries the method. It starts from context extracted
* off the incoming request headers so an upstream `traceparent` becomes its
* parent and nested channel operations 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 marks failure status and is rethrown; request
* spans never record exception content. 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 `traceChannelRequests: true`, the handler runs with no span (`undefined`)
* and performs no header extraction. The channel dispatcher can still use an
* already-active platform span for the activation's cross-trace link.
*
* 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<T extends Response>(input: TraceChannelRequestInput, handler: (span: Span | undefined) => Promise<T>): Promise<T>;