Logging Best Practices

Q: What fields are mandatory?

Minimum: level, time, msg, service, requestId (HTTP), event or equivalent action key.

Q: How verbose should error logs be?

Full err object in logs; generic message in HTTP response. Never the reverse.

Q: Multi-tenant SaaS?

Always include tenantId on child logger after tenant resolution. Critical for support queries.

Q: Audit logs vs application logs?

Separate stream or audit: true field with longer retention and stricter access RBAC.

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

What fields are mandatory?

Minimum: level, time, msg, service, requestId (HTTP), event or equivalent action key.

How verbose should error logs be?

Full err object in logs; generic message in HTTP response. Never the reverse.

Winston migration?

Wrap Pino for new code; migrate hot paths first. Fastify/NestJS favor Pino natively.

Should workers log to files?

No in k8s - stdout only. Platform collects and indexes.

Structured logging cost?

Pino is cheap relative to HTTP work. Cost explosion comes from debug verbosity and huge payloads.

Log sampling?

Sample debug 1-5% in prod if needed. Never sample errors or payment events.

Multi-tenant SaaS?

Always include tenantId on child logger after tenant resolution. Critical for support queries.

Audit logs vs application logs?

Separate stream or audit: true field with longer retention and stricter access RBAC.

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

Node.js Best Practices (GitHub) - Curated production best practices.
NodeSource Blog & Resources - Enterprise Node.js performance and security content.
DigitalOcean Node.js Tutorials - Production-oriented how-tos.
Node.js Cookbook, 5th Edition - Practical server-side recipes.
Distributed Systems with Node.js - Enterprise-ready distributed systems.

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.

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

What fields are mandatory?

Minimum: level, time, msg, service, requestId (HTTP), event or equivalent action key.

How verbose should error logs be?

Full err object in logs; generic message in HTTP response. Never the reverse.

Winston migration?

Wrap Pino for new code; migrate hot paths first. Fastify/NestJS favor Pino natively.

Should workers log to files?

No in k8s - stdout only. Platform collects and indexes.

Structured logging cost?

Pino is cheap relative to HTTP work. Cost explosion comes from debug verbosity and huge payloads.

Log sampling?

Sample debug 1-5% in prod if needed. Never sample errors or payment events.

Multi-tenant SaaS?

Always include tenantId on child logger after tenant resolution. Critical for support queries.

Audit logs vs application logs?

Separate stream or audit: true field with longer retention and stricter access RBAC.

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

Node.js Best Practices (GitHub) - Curated production best practices.
NodeSource Blog & Resources - Enterprise Node.js performance and security content.
DigitalOcean Node.js Tutorials - Production-oriented how-tos.
Node.js Cookbook, 5th Edition - Practical server-side recipes.
Distributed Systems with Node.js - Enterprise-ready distributed systems.

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.

Logging Best Practices

Search Documentation

Logging Best Practices