Structured logs in Node.js on pino: levels, query correlation and redact
Why structured logs
The User 42 created order 1001 in 120ms line is convenient for humans, but is useless for a log collection system: to find all orders of user 42, you need a regular template for each message option. A JSON record with the fields userId, orderId, durationMs is filtered and aggregated without parsing the text. pino writes just such records and does it with minimal overhead.
Basic configuration
// src/logger.ts
import pino from "pino";
export const logger = pino({
level: process.env.LOG_LEVEL ?? "info",
base: { service: "orders-api", env: process.env.NODE_ENV },
timestamp: pino.stdTimeFunctions.isoTime,
redact: {
paths: [
"req.headers.authorization",
"req.headers.cookie",
'res.headers["set-cookie"]',
"*.password",
"*.token",
"*.cardNumber",
],
censor: "[REDACTED]",
},
});baseis added to each entry:serviceandenvlogs of different services and environments are divided into a common storage.isoTimegives readable time instead of epoch milliseconds.redactreplaces values in specified paths. Works only for listed paths:*.passwordwill findbody.password, but notbody.user.password. This is insurance, not a substitute for discipline.
Logs are written to stdout. Collection, rotation and dispatch are the task of the environment (Docker, systemd, platform agent), not the application.
For development, connect pino-pretty as a transport locally only:
transport: process.env.NODE_ENV === "development" ? { target: "pino-pretty" } : undefined,In production, a human-readable format is not needed and interferes with parsing.
How to write posts
logger.info({ orderId, userId, amount }, "order created");
logger.warn({ orderId, attempt }, "payment provider timeout, retrying");
logger.error({ err, orderId }, "order creation failed");An object with fields is the first argument, a short constant message is the second. A message without variables is convenient for grouping: all “order created” are found in one filter. Pass the error in the err field: the standard pino serializer will extract type, message and stack. The Error object passed under a different name will become an empty {}.
Levels
| Level | When | |---|---| | fatal | the process cannot continue and will now terminate | | error | operation not completed, reaction (alert) needed | | warn | something went wrong, but processed: retry, degradation, limit failure | | info | significant business events and life cycle: start, order created, payment received | | debug | details for debugging, disabled in production | | trace | maximum detail, almost never |
A typical error is error for expected situations like an incorrect password or 404. Then the alert for the number of errors is triggered by bots, and they stop believing in it. Invalid password - info or warn, database error - error.
Query correlation
To collect all records of a single HTTP request, each must contain its identifier. It is inconvenient to pass the logger as an argument through all functions, so we use AsyncLocalStorage and the mixin option, which adds fields to each record:
// src/context.ts
import { AsyncLocalStorage } from "node:async_hooks";
export const requestContext = new AsyncLocalStorage<{ requestId: string; userId?: string }>();// src/logger.ts — дополнение к конфигурации выше
import { requestContext } from "./context";
export const logger = pino({
// ...прежние опции
mixin() {
return requestContext.getStore() ?? {};
},
});// src/app.ts (Express)
import express from "express";
import { randomUUID } from "node:crypto";
import { requestContext } from "./context";
import { logger } from "./logger";
const app = express();
app.use((req, res, next) => {
const incoming = req.get("x-request-id");
const requestId = incoming && /^[\w-]{8,64}$/.test(incoming) ? incoming : randomUUID();
res.setHeader("x-request-id", requestId);
const started = performance.now();
res.on("finish", () => {
logger.info(
{ method: req.method, path: req.path, status: res.statusCode, durationMs: Math.round(performance.now() - started) },
"request completed"
);
});
requestContext.run({ requestId }, next);
});Now logger.info(...) anywhere in request processing, including deeply nested services, contains requestId. Incoming x-request-id from the balancer is accepted after checking the format so that the client cannot insert arbitrary text into the logs. The same identifier is given in the response: the user can report it to support.
Express has a ready-made pino-http, and Fastify uses pino as a built-in logger with request.log and a request ID out of the box.
What not to log
- Passwords, tokens, API keys, cookies, headers
Authorization- in any form. - Confirmation codes and links to log in or reset your password.
- Card numbers and payment information.
- Entire request and response bodies. Log the selected fields, not
req.body: tomorrow they will add a field with passport data to the form, and it will silently go to the logs. - Personal data is unnecessary. Instead of email, in most cases
userIdis sufficient.
Logs are often stored longer and are accessible more widely than the database and end up with third-party collection services.
Diagnostics
- Logs do not appear in production. The level is set higher than required (
LOG_LEVEL=warn) or the process ends before the buffer is reset during asynchronous recording. For fatal errors, log synchronously and terminate the process after logging. - There is no `requestId` in the entries. Code is executed outside of
requestContext.run: in timers started before the request, or in queue handlers. Create your own context for them. - Empty error objects. The error was not sent to the
errfield.
When it's unnecessary
For a script of one hundred lines or a CLI utility, console.error is enough. Structured logs pay off when there are several instances of a service, a system for collecting logs, and the need to search by fields rather than with your eyes.