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.
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# Logging — Derived Rules
|
|
|
|
> Derives from `domains/observability/first-principles.md` P1 (Structured by Default), P3 (Sufficient Context), P6 (No Secrets in Observability).
|
|
|
|
## Structured by Default (P1)
|
|
|
|
- Logs are JSON (or structured key-value). Free-form text is for humans; machines need fields.
|
|
- Every log entry has: `timestamp`, `level`, `message`, `request_id`, plus domain-specific fields.
|
|
- A log you cannot query is a log you cannot use. Structure is the query API.
|
|
|
|
## Levels (P3 Sufficient Context)
|
|
|
|
| Level | When |
|
|
|-------|------|
|
|
| ERROR | Something failed; an operator must look |
|
|
| WARN | Something unexpected; not a failure but notable |
|
|
| INFO | Significant application events (start, stop, deploy, user signup) |
|
|
| DEBUG | Diagnostic detail; off in production by default |
|
|
|
|
- ERROR is not for "this branch ran." ERROR is for "this failed and someone should know."
|
|
- Logging everything at ERROR means nothing is an error. Alert fatigue is a defect (observability P7).
|
|
|
|
## Context (P3)
|
|
|
|
- Every log in a request includes `request_id` (correlation ID). Trace the request across services.
|
|
- Include the user ID, the action, the resource. "What was the user doing?" is answerable.
|
|
- A log that says `"failed"` with no context is worse than no log. It is noise.
|
|
|
|
## No Secrets (P6, domains/security P9)
|
|
|
|
- Never log tokens, passwords, API keys, session IDs, PII.
|
|
- Redact: replace the secret with `[REDACTED]` or a hash. Log the hash, not the value.
|
|
- Never log the full request body. It may contain a token, a password, or PII.
|
|
|
|
## Volume (P4 Cardinality Discipline, core C8 Economy)
|
|
|
|
- Don't log every request at INFO. Log significant events.
|
|
- A million logs a minute is not "good observability"; it is a storage bill and a signal-to-noise problem.
|
|
- Sample high-volume logs (P5 Sampling with Intent). Sample deliberately, not randomly.
|
|
|
|
## What Violates Logging Discipline
|
|
|
|
| Violation | Principle |
|
|
|-----------|-----------|
|
|
| `console.log("here")` | P1 (not structured) |
|
|
| `logger.error("done")` | P3 (wrong level) |
|
|
| `logger.info(req.body)` | P6 (secrets), volume |
|
|
| A log with no `request_id` | P3 (no correlation) |
|
|
| 10M logs/day at INFO | P4, C8 | |