Guide · Observability
Structured Logging Best Practices: Node.js
Structured logging makes production debugging possible. Here's how to do it right in Node.js.
Structured logs with correlation fields are how teams pass Observability checks. Primary control: Observability
"Error occurred." is not Observability
Plain-text logs without a `request_id` force you to reproduce failures instead of searching them. Structured logging in Node means JSON lines with stable fields—so CloudWatch or Datadog can filter an incident in seconds. That is how APRF Observability expects production telemetry to look.
A team logging free-form strings spent two days recreating a user failure. The same bug with `request_id` in every line would have been a single query.
Node defaults that work
Use Pino (fast) or Winston (flexible transports). Emit:
- `request_id` (from `express-request-id` or equivalent)
- `level`, `msg`, `time`
- optional `user_id`, route, error code—never passwords, tokens, or raw PII
Keep production at INFO/WARN/ERROR; leave DEBUG off unless briefly sampling. Ship to a central store—local disk on one pod disappears with the pod.
Correlate beyond HTTP
Pass the same ID into queues and AI/tool spans. Inconsistent field names (`requestId` vs `request_id`) break searches—pick one schema and lint for it.
Next: Observability
Open the related pillar specification for mandatory checks, artifacts, and pass conditions. Self-attest is optional.
Related
Frequently asked questions
- What is structured logging in Node.js?
- Structured logging uses JSON with consistent fields (request_id, user_id, error, timestamp). It makes logs searchable and traceable. Use Pino or Winston for Node.js.
- What should I log in production?
- Log request_id, user_id (if applicable), error, message, and timestamp. Never log passwords, tokens, or PII. Use log levels: ERROR, WARN, INFO.
- How do I add request_id to Node.js logs?
- Use express-request-id or similar middleware to generate a unique ID per request. Pass it through all services and include it in every log entry.