# Tracing — Derived Rules

> Derives from `domains/observability/first-principles.md` P2 (Correlation), P5 (Sampling with Intent), P10 (Debuggability Over Coverage).

## Distributed Tracing (P2)

- A trace is a tree of spans. Each span is a unit of work with a start, end, and context.
- `trace_id` ties spans across services. `span_id`/`parent_span_id` form the tree.
- Every request has a `trace_id`. Propagate it in headers (`traceparent`, W3C standard).

## Sampling (P5)

- Head-based: sample at the start. Simple, but you miss the interesting failures.
- Tail-based: sample at the end. Keep all errors, sample the successs. Better signal, harder to build.
- A 100% trace rate is too expensive. 1% is often enough for debugging.
- Sample deliberately: keep all errors, all slow requests, and a fraction of the rest.

## Context (P3 Sufficient Context, P10 Debuggability)

- A span has: name, start time, duration, attributes (key-value), events, status.
- Attributes: `http.method`, `http.url`, `db.statement`, `user.id`. The fields you need to debug.
- Events: notable points within a span (e.g., "cache miss", "retry").
- A span with no attributes is a span that tells you nothing.

## Where to Span (P4 Locality)

- Span at service boundaries (HTTP in/out, DB query, queue send/receive).
- Span at significant internal operations (a long computation, a batch step).
- Don't span every function call. Span the meaningful units.

## Traces vs Logs (P10)

- Logs are events; traces are causality. Logs answer "what happened"; traces answer "why it was slow."
- A trace contains log events (span events). They are not separate systems.
- Use traces for the request flow; use logs for the details.

## What Violates Tracing Discipline

| Violation | Principle |
|-----------|-----------|
| No `trace_id` propagation | P2 Correlation |
| 100% trace rate | P5 Sampling |
| Span per function | P4 (too noisy) |
| Span with no attributes | P10 (no debug value) |
| Traces for successful requests only | P5 (miss the failures) |