Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
2.0 KiB
2.0 KiB
Tracing — Derived Rules
Derives from
domains/observability/first-principles.mdP2 (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_idties spans across services.span_id/parent_span_idform 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) |