Requires W3C traceparent on every service hop, allowlists baggage, applies a declared sampling policy, and forbids PII in span attributes.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Every service-to-service call forwards a W3C Trace Context traceparent. Baggage is an allowlist, not an open carrier for tenant secrets. Sampling follows a declared policy so traces remain comparable. Span attributes never include PII, credentials, or raw payloads. Correlation ids in logs equal the trace-id from traceparent.
Scope
- Incoming and outgoing
traceparentandtracestate, baggage allowlist, sampling, span attribute policy, and log correlation for backend service-to-service calls. - Workers and async hops that continue a trace from a queue header.
- Deadline headers traveling with the same request, without putting deadline secrets in baggage.
Outside this block
- Field-level PII redaction for application logs beyond sharing the correlation id.
- Product analytics session replay.
Contract
- A service that receives
traceparentcontinues that trace on outbound HTTP, RPC, and queue jobs; it does not mint a new root because instrumentation was inconvenient. - Invalid
traceparentis rejected or ignored per the W3C parsing rules and a new root is created only when no valid parent exists. - Baggage keys not on the allowlist are stripped at the trust boundary; user email, tokens, and unconstrained tenant blobs cannot ride baggage.
- Sampling decision is recorded and propagated; child services do not silently resample to 100 percent in production.
- Span attributes use coded identifiers (tenant hash, route template), never raw email, names, or request bodies.
- Log correlation id equals the 32-hex trace-id from
traceparent.
Implementation guidance
- Implement W3C Trace Context as specified at the W3C Trace Context recommendation, including version and flag bits.
- Inject and extract in one shared client middleware so new outbound callers cannot forget headers.
Failure handling
- Missing trace on inbound public edge: create a root and continue; missing trace on internal mesh: emit a policy metric and still create a child rather than crashing.
- Baggage over size limits is stripped, not truncated into corrupt values.
- Exporter outage must not block requests; spans may drop with a metric.
Verification and operations
- Measure inbound traces without parent on internal routes, baggage strips, exporter drops, and traces with PII-shaped attributes (must be zero).
- Alert when production sampling silently exceeds the declared rate for a service.
- Prove with tests that a queue worker reuses the producer's trace-id from
traceparent.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.