Skip to content
Tutorials Center
My learning

Topics

Lesson 93 of 133 ยท Frameworks and Ecosystem

Logging and Observability

Learn Node.js logging and observability - structured JSON logs, levels, child loggers, correlation IDs with AsyncLocalStorage, metrics, health checks and tracing basics.

When your program runs on your laptop, you watch it. When it runs on a server at 3 a.m., the only thing that watches it is the log. Logs are the story your application tells about itself: what it did, what it decided, and what went wrong. If that story is vague ("something failed"), you will debug in the dark. If it is precise and searchable, you can often find the cause of a production problem in minutes.

This lesson starts with why console.log is not enough, then builds a small structured logger from scratch (so you understand exactly what libraries like pino and winston do for you), adds request correlation IDs with AsyncLocalStorage, and finishes with the other two pillars of observability: metrics and traces, plus health checks.

Logs, metrics and traces

People say "observability" for the ability to understand what a running system is doing from the outside. It rests on three kinds of data:

  • Logs are timestamped records of discrete events: "user 42 logged in", "payment failed".
  • Metrics are numbers sampled over time: requests per second, error rate, memory in use. They are cheap and good for dashboards and alerts.
  • Traces follow one request across many functions and services, showing where the time went.

You answer different questions with each one. Metrics tell you that something is wrong ("errors jumped at 14:02"). Traces tell you where ("the payment service is slow"). Logs tell you why ("card declined: insufficient funds for order 981").

Why console.log is not enough

console.log is fine for learning. In production it has real limits: no levels (you cannot silence noisy debug output), no machine-readable structure, no timestamps unless you add them, and no way to attach "which request is this?" to a line. Compare these two lines:

TEXT
user 42 failed to pay 19.99 for order 981 (card declined)
JSON
{"level":"warn","time":"2026-01-01T10:00:00.000Z","msg":"payment failed","userId":42,"orderId":981,"amount":19.99,"reason":"card_declined"}

A human can read the first. A machine can query the second: "show me every payment failed with reason card_declined for the last hour, grouped by userId". That is called structured logging: each log line is one JSON object, with a stable message and the variable details in separate fields. Log platforms (Loki, Elasticsearch, Datadog, CloudWatch and others) index those fields for you.

Two more details matter. First, console.log writes to stdout and console.error to stderr; twelve-factor style deployments treat logs as an event stream on stdout and let the platform collect them, so your app should not manage log files. Second, in Node.js, writes to a pipe or file may be asynchronous, so a process.exit() right after logging can lose the last lines. Let the process end naturally, or flush first.

Log levels

A level is the importance of a line. The common ladder, from loudest to quietest, is:

Level Number (pino) Use it for
fatal 60 The process cannot continue
error 50 An operation failed and needs attention
warn 40 Something odd happened but it was handled
info 30 Normal, important events (server started, order placed)
debug 20 Details useful while developing
trace 10 Very fine-grained steps

You pick a threshold, for example info, and everything below it is dropped. In development you run at debug; in production you run at info, and turn on debug temporarily when hunting a bug. The big benefit is that disabled calls are cheap, as long as you do not build expensive strings before the call.

A tiny structured logger

Let us build one. It needs a level threshold, a way to write JSON lines, and the ability to add context. Real libraries do exactly this, just faster. Note how we accept a write function, so tests (and this lesson) can capture the output, and a clock function so the timestamps are fixed.

Node.js A minimal structured JSON logger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice what happens with the debug call: nothing. The check value < threshold returns before any JSON is built. Notice also the design choice of putting the fields first and the message second, which is what pino does. The message stays a constant string, so you can search for it, and everything that varies lives in fields.

Never glue variables into the message ("payment failed for user 42"). Every distinct string becomes a different message in your log platform, and you lose the ability to group and count. Keep the message constant and put userId in a field.

Child loggers: adding context once

Most lines in one module share the same context: the component name, the request ID, the user. Repeating those fields on every call is noisy and easy to forget. A child logger carries fixed fields and merges them into every line. We extend our logger with a child method.

Node.js Child loggers carry fixed context

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Each line has service, component and requestId without the call site mentioning them. Child loggers are cheap, which is why web frameworks create one per request.

Logging errors properly

An Error object does not serialize usefully: JSON.stringify(new Error('x')) gives {}, because message and stack are not enumerable properties. If you log errors naively you will find empty objects in your logs exactly when you need them. A logger has to convert errors explicitly into plain data, including the cause chain you learned about in Error Handling in Node.js.

Node.js Serializing errors, including the cause chain

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

By convention the field is called err, which log tools recognise. Libraries like pino ship a standard serializer that does this for you; the point is to make sure it happens.

Correlation IDs with AsyncLocalStorage

On a busy server, log lines from hundreds of requests interleave. To follow one request you need a correlation ID (also called request ID) on every line it produces, including lines written deep inside your own modules. Passing a logger through every function is clumsy. AsyncLocalStorage solves it: store the request's child logger once, and let any code ask for "the current logger".

Node.js Request-scoped logger via AsyncLocalStorage

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

chargeCard never receives the request ID, yet every line it writes carries it. When the real order of lines between requests varies (it depends on timing), grouping by requestId always gives you a clean, ordered story for each request. In an HTTP server you would generate (or accept from an X-Request-Id header) the ID in the first middleware and wrap the rest of the handling in als.run. Return the ID in a response header so a user can quote it in a bug report.

What not to log

Logs live long and travel far, so treat them as semi-public.

  • Secrets and credentials: passwords, tokens, API keys, session cookies, full Authorization headers. See Secrets and Configuration.
  • Personal data you do not need: full card numbers, government IDs, health data. Log an internal ID instead of an email address when you can.
  • Whole request or response bodies by default: they are large and often sensitive.

A good defence is redaction: the logger replaces known sensitive field names with a placeholder before writing. Pino has a redact option for this; the idea fits in a few lines.

Node.js Redacting sensitive fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real libraries: pino and winston

You rarely write your own logger in production; you use one that is tuned for speed and has transports, serializers and redaction. These are read-only examples, because the runner has no npm packages.

pino is the usual choice when performance matters. It writes JSON lines to stdout and does very little work on the hot path; formatting for humans is a separate step (pino-pretty) that you only use in development.

JavaScript
// Needs: npm install pino   (read-only example: no npm packages in our editor)
import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  redact: ['req.headers.authorization', 'password'],
});

logger.info({ userId: 42 }, 'user signed in');

const requestLogger = logger.child({ requestId: 'req-1' });
requestLogger.warn({ orderId: 981 }, 'slow query');

winston is older and more configurable (multiple transports, custom formats) but slower. Either is a reasonable pick; what matters is that the output is structured JSON and that you use levels consistently.

Avoid writing log files from the app itself in containers or on platforms like systemd. Write to stdout and let the environment collect, rotate and ship logs. See Deploying Node.js Applications.

Metrics

A metric is a number you update as things happen, and a monitoring system samples it every few seconds. Three kinds cover most needs:

  • A counter only goes up (requests served, errors). You chart its rate.
  • A gauge goes up and down (open connections, queue length, memory).
  • A histogram records the distribution of values (request duration), so you can chart the median and the 99th percentile instead of a misleading average.

The industry standard is the Prometheus text format, exposed on a /metrics endpoint that the monitoring system scrapes. Libraries such as prom-client do this for you; the format is simple enough to see by hand.

Node.js A counter, a gauge and the Prometheus text format

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Be careful with labels: every unique combination of label values creates a separate time series. Labelling by method and status is fine; labelling by userId creates millions of series and can bring your monitoring system down. This problem is called high cardinality.

Node itself offers helpful numbers. process.memoryUsage() and performance.eventLoopUtilization() (see Performance Hooks) are good gauges for any service. Event loop delay is one of the best early warnings that your server is overloaded with synchronous work.

Health checks

A health check is an endpoint that load balancers and orchestrators (Kubernetes, Docker, your cloud) poll to decide whether to send traffic to an instance. Two kinds are common:

  • Liveness (/healthz): "is the process alive?" If this fails, the platform restarts the process. Keep it trivial; do not check the database here, or a database outage will make the platform restart every healthy app instance.
  • Readiness (/readyz): "can you serve traffic right now?" This may check the database and caches. If it fails, the instance is taken out of rotation but not killed.
Node.js Liveness and readiness endpoints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second readiness call shows the point: the instance stays alive (so it is not restarted) but asks to be removed from the load balancer until the database returns. Health checks also matter during shutdown, which is the subject of Graceful Shutdown and Health Checks.

Traces and OpenTelemetry

A trace describes one request's journey as a tree of spans. Each span has a name, a start time, a duration and attributes, and knows its parent. The root span is "GET /checkout"; its children might be "load cart", "call payment service" and "write order". Viewing the tree tells you immediately that 800 ms of a 900 ms request was spent waiting for the payment call.

Across services, the trace ID travels in an HTTP header (the W3C traceparent header) so spans from different processes join into one trace. You rarely implement this by hand. OpenTelemetry is the vendor-neutral standard: its Node.js SDK auto-instruments http, fetch, database drivers and frameworks, and exports spans to a collector or to a service such as Jaeger, Tempo or a commercial APM. It is configured at startup, before your application code is loaded:

Terminal
# Read-only: needs the OpenTelemetry packages from npm.
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

# Start your app with the instrumentation preloaded (no code changes needed):
node --import ./instrumentation.mjs server.mjs

The correlation ID you built above is a poor man's trace ID. If you adopt tracing, put the trace ID into every log line, so you can jump from a slow trace to its logs and back.

A practical checklist

  • Log JSON to stdout; let the platform collect it.
  • Use levels consistently; run info in production and make the level configurable by an environment variable.
  • Constant messages, variable data in fields.
  • One correlation ID per request on every line, carried by AsyncLocalStorage.
  • Serialize errors (with cause) and redact secrets.
  • Expose /healthz and /readyz, and a /metrics endpoint behind your network boundary.
  • Do not log inside tight loops; a line per item in a million-item job will cost more than the job.
  • Alert on symptoms users feel (error rate, latency), not on every error line.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main advantage of structured (JSON) logging over plain text lines?

    Each field is separately indexable, so you can query for all lines with a given userId or reason. Size and speed are not the point.
  2. 2. Why should you keep the log message constant and put variable data into fields?

    If the user ID is baked into the message, every line is a unique string and cannot be grouped. A stable message plus fields keeps both.
  3. 3. What does JSON.stringify(new Error('boom')) return?

    message and stack are non-enumerable own properties, so JSON.stringify skips them. A logger needs an explicit error serializer.
  4. 4. What is the best way to put a request ID on log lines written deep inside your modules?

    A global would be overwritten by concurrent requests. AsyncLocalStorage keeps one value per asynchronous flow.
  5. 5. A database outage happens. Which health endpoint should report failure so traffic stops, without the platform restarting every app instance?

    Readiness removes the instance from rotation. A failing liveness check would trigger restarts, which does not fix a database problem.

Summary

  • Observability combines logs (why), metrics (that) and traces (where).
  • Log structured JSON to stdout, with levels, constant messages and details in fields; let the platform collect the lines.
  • Child loggers add fixed context once; AsyncLocalStorage carries a per-request logger or correlation ID to any depth.
  • Errors must be serialized explicitly (with cause), and secrets and personal data must be redacted or left out.
  • Counters, gauges and histograms feed dashboards; watch out for high-cardinality labels.
  • Liveness checks answer "is the process alive", readiness checks answer "can it serve traffic".
  • Tracing with OpenTelemetry shows where time goes across functions and services.

Next: Project Structure and Architecture