Observability
Trigger phrases: "observability", "structured logging", "structured log", "add a trace", "add a metric", "correlation id", "add logging"
Goal: to be able to answer "what happened, where, why" during a production incident by looking at the logs.
It is stack-agnostic; when you need a framework-specific library/format, do a web search.
Three signals
- Log — event record (structured/JSON, leveled).
- Metric — numeric time series (request count, latency, error rate, resource usage).
- Trace — a request's journey across services (spans + correlation id).
Checklist
How
- Structured logger — set up/use one whose output is machine-readable (JSON). Search for the library the framework recommends.
- Correlation id: generate it at the entry point (HTTP middleware / message consumer) or take it from the incoming
X-Request-Id/trace header; put it in the log context; propagate it to downstream calls.
- Level discipline: INFO = business event, WARN = expected-but-noteworthy, ERROR = needs intervention. DEBUG is off/sampled in production.
- Context fields:
event, correlation_id, user_id (not PII, an opaque id), duration_ms, outcome. Do not embed them in free text.
- Metrics: at minimum RED (Rate, Errors, Duration) or USE; plus business-critical counters. Search for the framework's metrics library.
- Trace (in a distributed system): start/end spans, bind the correlation id to the trace id.
PII / secret leakage (critical)
Never to the log: password, token, API key, card number, national/ID number, full email/phone body, raw request body.
- Mask:
user@***, card **** 1234, token sk-p…789.
- When needed, log an opaque id (hash/uuid), not the raw value.
- This axis overlaps with
security-scan (sensitive data in logs) and privacy-compliance (KVKK/GDPR) — if personal data is involved, trigger those too.
Invariant rules
- Structured > free text — greppable, parseable.
- Correlation id on every line — without it, a distributed error is untraceable.
- No PII/secret is logged — mask it or use an opaque id.
- Do not make noise — every line must answer a question; do not add meaningless spam logs.
- Match the existing format — if the repo has a logger, follow its pattern; do not impose a new one.
1---2name: observability3description: Stack-agnostic observability: structured logs, correlation ids, metrics and traces; no PII or secrets in logs. Makes a production issue traceable to why it happened. Use when adding a log line, an error path, a metric, or when an incident could not be traced.4---56# Observability78<!-- routing-eval reads this line; it lives in the BODY so the always-on skill LISTING stays inside9 Claude Code's budget (1% of the context window) — an overflowing listing gets descriptions10 truncated or dropped, which strips the very keywords a match depends on. -->11Trigger phrases: "observability", "structured logging", "structured log", "add a trace", "add a metric", "correlation id", "add logging"1213Goal: to be able to answer "what happened, where, why" during a production incident **by looking at the logs**.14It is stack-agnostic; when you need a framework-specific library/format, do a web search.1516## Three signals17- **Log** — event record (structured/JSON, leveled).18- **Metric** — numeric time series (request count, latency, error rate, resource usage).19- **Trace** — a request's journey across services (spans + correlation id).2021## Checklist22- [ ] Logs are **structured** (JSON/key-value), not string interpolation23- [ ] Every log line carries a **correlation id** (request/trace id)24- [ ] Levels are correct: the DEBUG/INFO/WARN/ERROR distinction is meaningful25- [ ] **No PII/secret is logged** (password, token, card, national/ID number, email body)26- [ ] Error logs carry context (input summary, user/resource id — not PII); the stack trace does not leak to the user27- [ ] Critical business metric + infrastructure metric are emitted (where applicable)28- [ ] The correlation id is **propagated** across service-to-service calls (header/propagation)2930## How311. **Structured logger** — set up/use one whose output is machine-readable (JSON). Search for the library the framework recommends.322. **Correlation id**: generate it at the entry point (HTTP middleware / message consumer) or take it from the incoming `X-Request-Id`/trace header; put it in the log context; **propagate** it to downstream calls.333. **Level discipline**: INFO = business event, WARN = expected-but-noteworthy, ERROR = needs intervention. DEBUG is off/sampled in production.344. **Context fields**: `event`, `correlation_id`, `user_id` (not PII, an opaque id), `duration_ms`, `outcome`. Do not embed them in free text.355. **Metrics**: at minimum RED (Rate, Errors, Duration) or USE; plus business-critical counters. Search for the framework's metrics library.366. **Trace** (in a distributed system): start/end spans, bind the correlation id to the trace id.3738## PII / secret leakage (critical)39**Never** to the log: password, token, API key, card number, national/ID number, full email/phone body, raw request body.40- Mask: `user@***`, card `**** 1234`, token `sk-p…789`.41- When needed, log an **opaque id** (hash/uuid), not the raw value.42- This axis overlaps with `security-scan` (sensitive data in logs) and `privacy-compliance` (KVKK/GDPR) — if personal data is involved, trigger those too.4344## Invariant rules451. **Structured > free text** — greppable, parseable.462. **Correlation id on every line** — without it, a distributed error is untraceable.473. **No PII/secret is logged** — mask it or use an opaque id.484. **Do not make noise** — every line must answer a question; do not add meaningless spam logs.495. **Match the existing format** — if the repo has a logger, follow its pattern; do not impose a new one.
byerlikaya