# Tracing standards

Goals
- Consistent distributed tracing across services, workers, and CLI.
- Safe for offline and air-gapped deployments.

Context propagation
- Use W3C traceparent and baggage only.
- Preserve incoming trace_id and create child spans per operation.
- For async work, attach stored trace context as links rather than a new parent.

Span conventions
- Names use <component>.<operation> (example: policy.evaluate).
- Required attributes: tenant, workload, env, region, version, operation, status.
- HTTP spans: http.method, http.route, http.status_code, net.peer.name, net.peer.port.
- DB spans: db.system, db.name, db.operation, db.statement (no literals).
- Message spans: messaging.system, messaging.destination, messaging.operation, messaging.message_id.
- Errors: status=error with error.code, redacted error.message, retryable.

Sampling
- Default head sampling: 10% non-prod, 5% prod.
- Always sample error or audit spans.
- Override via Tracing__SampleRate per service.

Offline posture
- No external exporters; emit OTLP to local collector or file.
- UTC timestamps only.