Crate osproxy_observe 

Observability.

Emits the per-request causal trace (shapes, ids, field names, never values, docs/05) and assembles the /debug/explain/{request_id} document for LLM consumption. Read-only: it never mutates routing or cluster state (docs/decisions/005).

The RequestTrace is shape-only by construction, its setters accept only id newtypes, compile-time labels, and sizes, so there is no API path by which a tenant value or secret can reach telemetry (docs/05 §7). The ExplainStore retains the most recent explanations for the debug endpoint.

Directive evaluation (runtime verbosity control) lives in osproxy-control; resource_spans encodes that same shape-only trace as an OTLP/HTTP JSON payload for export (the wire emission is the I/O layer’s job, M7).

Structs

BreakGlassBuffer

A bounded in-memory ring of recent explanation documents, captured on demand.

ClassifyInfo

The classify span: how the request path was categorized.

DiagnosticsDirective

One diagnostics directive: target, verbosity, sampling, and expiry.

DirectiveMatch

What a directive targets. A request matches when every set field equals the request’s corresponding attribute; an unset field is a wildcard, so an all-unset match targets every request.

DirectiveSet

The set of active directives, evaluated per request. Cheap to evaluate (a filtered scan); typically a handful of directives are active at once.

DispatchInfo

The dispatch span: the upstream call outcome.

EgressInfo

The egress span: what was returned to the client.

ExplainStore

A bounded, in-memory store of recent request explanations.

InMemoryDirectiveStore

The in-process reference store: a controller (or an admin endpoint) publishes a new set and proxy threads load it. Swappable for a distributed DirectiveStore without touching the pipeline (docs/05 §3).

IngressInfo

The ingress span: how the connection was framed (docs/05 §2).

Metrics

Live, lock-free counters a proxy increments as it serves data-plane requests. Cheap enough to update on every request (three relaxed atomic adds); the snapshot is taken on demand when an agent scrapes.

NoVerifier

The default: no header channel is configured, so every header is rejected.

NoopDiagnosticSink

The default sink: off-instance emission is disabled, so a directive-selected capture stays in the local break-glass ring only (single-instance).

NoopExporter

The default exporter: export is disabled, so the pipeline never encodes a payload and nothing is shipped.

PoolSnapshot

One upstream cluster’s connection-reuse counters, the signal that the pool is amortizing TLS/TCP handshakes (opened far below dispatched). cluster is an infrastructure id, not tenant data.

RequestAttrs

The attributes of a request, evaluated against directive matches. The tenant is optional because it is only known after partition resolution.

RequestTrace

The accumulated causal trace for one request, filled stage by stage.

ResolveInfo

The spi.resolve span: the routing decision and its inputs.

RewriteInfo

The rewrite span: what the body transform did (in shapes).

StatsSnapshot

A single proxy instance’s operational snapshot. Per-instance by definition; the fleet rollup is the external aggregator’s job. Safe to serve unauthenticated, it is shape-only.

Enums

DiagLevel

How much detail to record for a request (ordered: higher = more verbose).

Traits

DiagnosticSink

Receives directive-selected diagnostic documents (each a /debug/explain doc) for delivery to a fleet-wide store/aggregator, keyed by the trace_id the doc carries.

DirectiveStore

The backend holding the fleet’s active diagnostics directives. Proxy instances poll it fresh per request; a controller publishes new sets into it.

DirectiveVerifier

Verifies a signed X-Debug-Directive request header into the directive it authorizes, the surgical, single-request delivery channel (docs/05 §3). The signature means a client cannot self-enable verbose diagnostics without the operator’s key (NFR-S3); the directive follows the request to whatever instance handles it. The concrete implementation (HMAC + the token format) lives in a crypto-capable crate behind this seam.

SpanExporter

Receives finished OTLP span payloads for delivery to a collector.

Functions

decode_directive_set

Decodes a publish body into a DirectiveSet, or a stable value-free reason slug on the first malformed field.

explain_json

Builds the explain document for request_id from its trace.

resource_spans

Builds the OTLP/HTTP JSON ResourceSpans envelope for one completed request, or None if the request never recorded a trace context (no ids to emit).