# 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 |