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.
45 lines
2.0 KiB
Markdown
45 lines
2.0 KiB
Markdown
# 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) | |