Logging — Cross-Language Methodology

Every log line has exactly two legitimate readers: the operator reconstructing an incident and the developer reproducing a bug. A line that serves neither is cost — storage, noise, and attention stolen from the lines that matter. Everything below derives from that.

This reference is deliberately stack-agnostic. It never tells you which logging library to use — the ecosystem table in SKILL.md owns stack defaults, and the project's existing practice overrides everything (Rule 0).

---

Rule 0 — Discover the project's practice before emitting anything

BEFORE adding a single log line, find out how this project logs. Grep for the logger initialization, a wrapper module, prior art in sibling files, and the project's agent docs (AGENTS.md / CLAUDE.md).

What you find	Required behavior
A designated logger or wrapper	Use it exactly — its levels, its field conventions, its error-passing shape. Copy the call shape of the nearest well-written call site, not your habit.
A logging lib you like better	Irrelevant. NEVER introduce a second logging framework into a project that already has one.
Raw console.* / print culture	Follow it for user-facing CLI output. For diagnostics, propose structured logging in your reply — do not unilaterally convert the project.
No logging at all (library, small CLI, script)	Respect the absence. A library that suddenly logs is a behavior change its consumers never asked for; a 40-line script does not need a logging framework. If logging would genuinely help, say so in your reply — add it only when the user asks or the task itself is about observability.

Bypassing the project's designated logger with a bare console.log / print "just for this one line" is the logging equivalent of as any: it escapes every contract the project set up — stage routing, formatting, redaction, shipping.

Serialization contracts (reserved field names, argument order, the key an Error must be passed under) are project knowledge. Discover the contract from the logger config and existing call sites; if the project's agent docs do not record it, record what you found there as part of your change.

Greenfield — when you own the setup

A new service earns exactly this much logging infrastructure, and no more:

1. One init module. Callers import a ready logger; only the init module knows the stage. No call site ever checks NODE_ENV-style vars to decide how to log.
2. Stage split by environment. Dev = human-readable (pretty, colorized). Prod = structured, machine-parseable (JSON to stdout). Same logger API on both — the stage changes the sink and format, never the call sites.
3. Level threshold per stage. Dev = debug, prod = info, overridable with a LOG_LEVEL-style env var.
4. The stack's standard structured logger (the ecosystem table in SKILL.md names the default) — never a hand-rolled one.
5. Error-serialization proof. Before trusting error logging, pass a real Error/exception through the PROD formatter once and assert the output preserves type, message, and stack. Every structured-logging stack has a reserved-key contract, and violating it typically produces an empty {} where the stack trace should have been — discovered during the incident. This is a one-line test; write it at setup time and the whole bug class is dead permanently.

Choosing the level — consumer, not severity

A level is a routing decision, not a severity vibe. Choose it by naming who consumes the line and what they do about it. If you cannot name the consumer, do not emit the line.

Level	Consumer and action	The line earns this level when
error	Alerting wakes a human NOW	The service failed at a user-visible operation and cannot recover on its own.
warn	Reviewed in batch — dashboards, weekly triage	The request SUCCEEDED but took an abnormal path: retry needed, fallback engaged, degraded mode, suspicious data.
info	Read during an incident to reconstruct the timeline	A state transition without which the request's story does not reconstruct: session/job/connection created, completed, destroyed.
debug	The developer reproducing locally	Detailed tracing. Does not exist in prod.

Two corollaries that get violated constantly:

• error means the SERVICE failed, not the request. A 4xx is the client's mistake handled correctly — that is warn at most, info for routine misses. Reserve error for 5xx-class outcomes: the service could not do its job. Log 4xx as error and the alert channel drowns in noise from every crawler probing /wp-admin; a drowned alert channel is equivalent to no alerting.
• A failure logged at info is invisible. If the message says "failed", the level is warn or error — never info.

Placement — log decisions, not work

Log where the system decides something, not where it does something:

• Boundaries — request in / response out, calls to external systems (and their failures).
• State transitions — create / complete / destroy of sessions, jobs, connections.
• Decision points — retry chosen, fallback engaged, cache bypassed, degraded mode entered.
• The one place an error is finally handled.

Never log inside pure functions, utilities, or private helpers — callers with context log outcomes; internals stay silent. Two mechanical rules:

• One event, one line. Log-and-rethrow at every layer turns one incident into five look-alike incidents. Log where the error is handled; layers that only propagate stay silent.
• Mechanical logging belongs to middleware. Request/response logging is wired once at the framework layer, never hand-assembled per handler. High-volume zero-signal paths (health probes, metrics scrapes) are excluded there as data — an exclusion set — not as scattered if statements.

No speculative logs. "Might need it later" is not a consumer. A log line earns its place through evidence: a debugging session that burned rounds because this state was invisible (see the debugging bridge below), an incident postmortem, an alert that needs the field.

The line contract

• The message is a stable, grep-able constant; data goes in fields. logger.warn({orderId, attempt}, "payment retry") — never `retrying payment for ${orderId}`. An interpolated message cannot be counted, aggregated, or alerted on.
• Correlation or it did not happen. Request-scoped lines carry the trace/request id; entity-scoped lines carry the entity id. A line you cannot join to its request is noise during the only moments logs matter.
• Name events semantically (session.destroy, payment.fallback), never positionally ("Step 3"). Step numbers couple the log stream to today's call structure; the first refactor makes them lie.
• No secrets. Tokens, credentials, session cookies, and PII never enter a log line; URLs are sanitized (strip or redact query params like token, key) before logging. A leaked log is a leaked credential.
• The logging path may not break the program. If a log call can itself fail (serializing exotic state, a wrapper that touches I/O), that failure is caught, downgraded to a warn through a channel that cannot fail, and the operation continues. An empty catch around logging is still an empty catch.

Anti-patterns

Anti-pattern	Why it fails
console.* / print bypassing the project's designated logger	Escapes stage routing, redaction, and shipping — invisible in prod
Introducing a logging framework to a project that has none	Uninvited behavior change; Rule 0 violation
4xx logged as error	Alert noise buries real pages
Log-and-rethrow at every layer	One incident looks like five
Variables interpolated into the message string	Un-aggregatable, un-alertable
"Might need it later" logs	No consumer → pure cost
Debug-time prints promoted to permanent info	Narration, not state transitions
Trusting Error serialization without the proof	error: {} in prod, discovered during the incident

Debugging bridge — how logs earn their place

When a debugging-skill session takes extra rounds because state was invisible — no line told you which branch ran, what the value was, whether the fallback engaged — that invisibility is a defect adjacent to the bug. The fix ships with the log line that would have made diagnosis one round: placed at a decision point, leveled by consumer, fields not interpolation, through the project's designated logger.

The inverse also holds: every temporary print / dbg! / console.log planted during diagnosis is a debug artifact and gets scrubbed at cleanup. The triage between the two is the consumer test — a line whose ongoing consumer you can name is part of the fix; a line that only served today's session is an artifact.