Tracing: Instrumentation design

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 traceparent and tracestate, 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 traceparent continues that trace on outbound HTTP, RPC, and queue jobs; it does not mint a new root because instrumentation was inconvenient.
• Invalid traceparent is 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.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• w3c-trace-context