Monitoring & Observability
Enough signal to answer a real question from logs alone, and nothing that can change a result.
Overview
Observability here is scoped by a single question: can someone answer "it was failing around two o'clock" without reproducing it? That question decides what gets recorded, what never gets recorded, and where the work stops. This document covers the observation contract, correlation, what must never be logged, the diagnostics that earn their place, and how to know when to stop building.
Why This Exists
Design for the operator you actually have. With no on-call rotation, no platform team and no vendor, whatever cannot be diagnosed from logs alone, at nine in the morning, by one person, effectively cannot be diagnosed at all. That constraint is more useful than any list of pillars, because it rules things out. It says what to add: identity on every line, so a report can be located in time and space. It says what to skip: anything that requires a second system to interpret. And it sets a stopping point, which is the part most observability work lacks.
Observation must be incapable of changing behaviour
Identity on every line
What must never be recorded
Diagnostics that earn their place
Knowing when to stop
Health checks are part of this, and are not the same as logs
Related Principles· 3
Related Documents· 4
Referenced By· 7
Version History
- v0.1.0
Initial structure and metadata established.
- v0.2.0
Written from real experience. Covers the inert-observation contract, correlation and static identity, privacy enforced structurally rather than by discipline, the diagnostics that repeatedly answer real questions, the rule for stopping, and the liveness/readiness split.