Logging Best Practices

Log actionable fields; sample debug in prod sparingly. These rules keep Node.js logs searchable, compliant, and cheap at scale.

How to Use This List

• Review on every new middleware, outbound client, and worker processor.
• Pair with PII Redaction & Compliance before SOC2.
• Add CI snapshot test for redact paths on sample payloads.
• Align field names (requestId, tenantId) across microservices in a shared doc.

A - Structure and Levels

• One JSON object per line to stdout. No string concatenation or multi-line stack dumps as plain text.
• Stable event or action field for business logs. order_created, not vague done.
• info for request lifecycle and business events. error for failures needing action.
• debug off or sampled in production. LOG_LEVEL=info default; tail sampling for investigations.
• Ban console.log in src/ via ESLint. Exception for CLI entrypoints only.

B - Request Context

• Accept or generate x-request-id at edge. Return same ID in response header.
• Child logger or ALS for requestId on every line. No manual pass-through in deep layers without ALS.
• Forward x-request-id on outbound HTTP and queue jobs. End-to-end correlation.
• Log method, path, status, duration on completion. Exclude /health or log at debug.
• Bind userId/tenantId after auth on child logger. Not before authentication succeeds.

C - Security and Compliance

• Pino redact for authorization, cookies, passwords, PAN. See pino.
• Custom serializers drop PII from req and user objects. Log IDs, not emails.
• Document log retention TTL per environment. GDPR-aligned 30-90 days typical for prod.
• Separate log indexes per environment. No prod traffic in dev aggregators.
• Never log full req.body or Axios error.response.data by default.

D - Performance and Operations

• No pino-pretty in production. JSON only; pretty transport blocks the event loop.
• Avoid logging inside tight loops. Aggregate counts or sample 1/N.
• Single root logger per process with base: { service, version }. Searchable fleet metadata.
• Ship logs via stdout + agent sidecar. Not app-level file rotation in containers.
• Alert on log volume spikes. Often indicates error storms or debug left on.

E - Observability Integration

• Share trace_id with OpenTelemetry when enabled. Correlate logs and traces in APM.
• Use consistent severity mapping for PagerDuty. fatal pages; error tickets; warn dashboard.
• Runbook links in alert descriptions, not in every log line. Keep log payloads small.
• Test log output in CI for redaction regressions. Snapshot sensitive fixture.
• Document required fields in LOGGING.md for new services.

FAQs

Related

• Logging Basics - introductory examples
• pino - configuration reference
• Request Correlation IDs - header propagation
• Observability Best Practices - metrics and traces

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.