Module telemetry 

A span for every request, and the identifiers that tie its log lines together.

RequestTraceLayer is the outermost layer of the router. For each request it:

• takes the client’s x-request-id if it is usable, or makes one, and echoes it on the response;
• reads the W3C traceparent (and tracestate) into a TraceContext, or starts a trace, and puts the context in the request’s extensions for the REST pipeline and GraphQL to find;
• opens a span named request, at info, whose fields are OpenTelemetry’s HTTP server conventions, and records the status on it when the response is ready;
• logs one line at debug with the status and latency.

Field names are the OpenTelemetry semantic conventions, spelled as tracing-opentelemetry reads them – otel.kind, otel.status_code – so an exporter can be added beneath this without renaming anything.

Why the span is at info and the line at debug

The span is what makes an error logged deep in the engine say which request it belonged to: every line written inside it carries request_id and trace_id. That is worth having at the default level, and it costs the formatting of a handful of borrowed fields per request.

The per-request line is not. At the default info it would be a line for every request a busy server answers, and the failures worth seeing are already logged where they happen, with their cause – a query fault at error, a refusal at debug (see query_error_log in postrust-engine). A second line at error for every 5xx would say the same thing again with less in it. So the request line is at debug, whatever its status, and a 5xx is marked on the span as otel.status_code = "ERROR" for a trace backend to find.

Structs

RequestTrace

The service RequestTraceLayer produces.

RequestTraceLayer

Wraps a service so that every request gets a request id, a trace context and a span. See the module documentation.

ResponseFuture

The response future of RequestTrace.

Constants

REQUEST_ID_HEADER

The header a request id travels in, both ways.

Functions

new_request_id

A new request id: a version 4 UUID, in its usual spelling.

new_trace_id

A new trace id, for a request that did not arrive as part of one.

request_id

The client’s x-request-id, if it sent exactly one that can be used as given, or a new one.