Choose the boundary to observe
The observability package provides OpenTelemetry-oriented primitives with vendor-neutral signal and error-reporting ports. Its canonical signal/evidence declarations validate supplied observations; emission, persistence and backend selection belong to the instrumentation facade and host. Start with one operation and the question you need to answer: latency, failure cause, denied authority, queue delay or provider outcome. Emit identifiers and safe evidence references that let an operator correlate those events without copying the full business payload.
Preserve context and privacy
The source documents W3C trace carrier helpers across HTTP, queues, jobs, webhooks and MCP. It also describes default privacy filtering and bounded dispatch that isolates exporter outages from business work. Inspect the exact carrier boundary and its validation rather than manually concatenating trace headers. Keep operational trace state distinct from durable domain evidence: a missing telemetry event should not be interpreted as proof that a business effect did or did not happen.
Match the test to the claim
Testing utilities include contract-aware runners, recording and generation surfaces; conformance and agent-evaluation packages provide other targeted checks. Select a check that can falsify the behavior being documented. Static source inspection can show a declared operation; a handler fixture can demonstrate a local result; a transport test can qualify encoding and context; a clean package consumer can reveal distribution problems. Provider-backed and deployed evidence require their own environment and should not be inferred from those earlier checks.
Follow a practical path.
Trace a successful and denied request
Follow correlation from the caller through the adapter, handler and any queued/provider work. Compare a valid request with a policy or validation denial and inspect which safe identifiers remain available for diagnosis.
Choose one concrete regression
Use the owning package’s existing fixture or test surface for the failure you are addressing: replay, wrong scope, schema mismatch, provider timeout or translation/context drift. Avoid a check that merely restates the implementation.
Record what the result establishes
Attach the source revision, package/environment context, command or test identity and observed outcome. Keep unexecuted source examples and source-present APIs labeled accordingly, so a later release or product page can make a defensible availability claim.