What is pino structured logging and why does it keep formatting out of the hot path?
Pino writes each log entry as a single line of JSON terminated by a newline (NDJSON). Every line is a self-contained record with a numeric level, a time timestamp, msg, and whatever fields you bind. Log shippers and central stores can parse each line independently, so you can filter on userId or route without regex-scraping free text.
Pino keeps the logging call cheap by doing as little as possible on the main thread. Serializing an object to JSON and writing it to stdout is fast. Colorizing output, reformatting timestamps, or shipping to a remote endpoint is slower, and in a Node process that work competes with request handling on the same event loop. Pretty-printing belongs in local development, by piping output through pino-pretty (node app.js | pino-pretty). Delivery to a log backend belongs in a transport running off the main thread, or in a separate collector that reads stdout.
Two features carry most of the production value. Child loggers attach bindings such as a request ID once, and every line from that child includes them. Redaction strips or masks configured paths, such as req.headers.authorization, before the record is serialized. Context and secret-handling then live in configuration rather than in each logger.info() call, so a hurried call site can't leak a token or drop the correlation ID.
A minimal production config sets level from an environment variable, declares redact paths, and writes plain JSON to stdout. This suits backend and platform teams running Node services whose logs feed a central store.
// logger.js: production logger that writes plain NDJSON to stdout.
// No pretty-printing or transports here; formatting and shipping happen elsewhere.
const pino = require('pino');
const logger = pino({
// Set verbosity per environment without a code change.
level: process.env.LOG_LEVEL || 'info',
// Mask secrets before serialization, so individual call sites can't leak them.
redact: {
paths: ['req.headers.authorization', 'req.headers.cookie', '*.password'],
censor: '[REDACTED]',
},
});
// A child logger binds request context once. Every line it writes includes reqId.
function handleRequest(req) {
const log = logger.child({ reqId: req.id, route: req.url });
log.info({ req: { headers: req.headers } }, 'request received');
log.info({ user: { name: 'alice', password: 'example-only' } }, 'login attempt');
}
handleRequest({
id: 'req-7f3a',
url: '/login',
headers: { authorization: 'Bearer placeholder-token', accept: 'application/json' },
});
// Production: node logger.js -> one JSON object per line on stdout
// Local dev only, pretty-print in a separate process via a pipe:
// node logger.js | npx pino-pretty
A minimal production Pino config that emits NDJSON to stdout, uses redact paths to mask secrets and a child logger to bind request context, and leaves pretty-printing to a dev-only pino-pretty pipe.
How does pino work under the hood?
A call such as log.info({ userId }, 'saved') goes through a short, fixed pipeline:
- Level check. The logger compares the call's level against its configured
level. If the call is below the threshold, the method returns almost immediately. That is why leavingdebugcalls in production code costs little when the level isinfo. - Assemble the record. Pino combines the numeric level, the timestamp, the
basefields (by defaultpidandhostname), the child logger's bindings, the object you passed, andmsg. Child bindings are serialized once, when the child is created, and the resulting fragment is reused on every line rather than re-serialized per call. - Apply serializers and redaction. Serializers registered for a key (for example
req,res,err) transform that value. Redaction paths, compiled once when the logger was created, then censor or remove the matching fields. - Serialize to one JSON line. The record becomes a single string terminated by a newline.
- Write to the destination. By default this is stdout. You can pass any writable stream, use
pino.destination()for a file descriptor or file path (synchronous or buffered asynchronous), or usepino.transport()to hand lines to a worker thread that formats or ships them.
Everything after step 5 (pretty-printing, enrichment, shipping to a backend) happens outside the request path: in a worker-thread transport, in a separate process reading a pipe, or in a log collector reading the container's stdout. The application process does the minimum needed to produce a correct, redacted JSON line.
How does pino redact work, and should you censor or remove fields?
The redact option takes either an array of paths or an object with paths, censor and remove keys. Paths are compiled once when the logger is created, so a malformed path throws at startup rather than silently leaking at runtime. Explicit dot paths such as req.headers.authorization, req.headers.cookie and user.password are the cheapest and most predictable form. Keys containing hyphens or dots need bracket notation, for example req.headers["x-api-key"]. Without brackets, the path parser would read the hyphen or dot as part of the path syntax rather than as part of the key.
Wildcards cover keys you cannot name in advance. users[*].token matches every element of an array, and *.password matches a password key under any top-level object. They are convenient but carry two costs. Wildcard matching does more work per log call than a fixed path, and intermediate wildcards are typically the most expensive. Broad patterns can also over-redact, hiding fields such as a password boolean flag that you wanted to keep. Benchmark your own service before assuming the overhead is negligible.
| Option | Output for a redacted field | Effect on queries and dashboards |
|---|---|---|
| Default censor | Value replaced with "[Redacted]" |
The field still exists, so "field exists" filters still match |
Custom censor string |
Value replaced with your string, such as "***" |
Same as default, and the marker is consistent across services |
remove: true |
Key dropped entirely | "Field exists" filters stop matching, and panels keyed on the field go empty |
Prefer a censor string when dashboards or alerts depend on a field being present. Use remove when the field's existence is itself sensitive or adds unwanted volume.
const pino = require('pino');
// Paths are compiled when the logger is created; a malformed path throws here.
const paths = [
'req.headers.authorization',
'req.headers.cookie',
'user.password',
'req.headers["x-api-key"]', // bracket notation: the key contains a hyphen
'users[*].token' // wildcard: every element of the users array
];
// Censor: the key stays, so "field exists" filters and dashboard panels keep working.
const censored = pino({ redact: { paths, censor: '***' } });
// Remove: the key is dropped entirely, so presence-based queries stop matching.
const removed = pino({ redact: { paths, remove: true } });
const entry = {
req: {
headers: {
authorization: 'Bearer example-token-123',
cookie: 'session=placeholder',
'x-api-key': 'test-key-000',
'user-agent': 'curl/8.0'
}
},
user: { id: 42, password: 'not-a-real-password' },
users: [{ id: 1, token: 'tok-a' }, { id: 2, token: 'tok-b' }]
};
censored.info(entry, 'login attempt');
// ... "authorization":"***", "x-api-key":"***", "user-agent":"curl/8.0" ...
removed.info(entry, 'login attempt');
// ... "headers":{"user-agent":"curl/8.0"}, "user":{"id":42}, "users":[{"id":1},{"id":2}] ...
// Omitting censor and remove uses the default value "[Redacted]".
The same redact paths (explicit, bracket notation for a hyphenated header, and an array wildcard) are applied once with a custom censor string, which keeps keys present, and once with remove: true, which drops the keys from the output.
When does redaction fail, and what are the alternatives to path-based redaction?
Redaction only rewrites the object paths you list, so it misses more than most teams expect. It never inspects the message string, so log.info(\token=${t}`)goes out intact. Error messages and stacks pass through untouched, and some libraries put the failing URL, query string or credentials in them. A field renamed fromtokentoaccessTokenfalls outside the listed paths, as does a newx-api-key` header someone adds next quarter. Redaction also has no effect outside pino: reverse-proxy access logs, crash dumps, child process stdout and APM agents capture data on their own.
The deeper issue is that path redaction is a denylist. You list what to hide, so anything you didn't anticipate leaks. Serializer-based allowlisting inverts this. A serializer runs for a given key and returns only the fields you choose. Pino ships standard serializers for req, res and err (exposed as stdSerializers). You can replace or wrap them, and you can write custom serializers that reduce large or sensitive objects to an ID and a few safe properties.
| Path redaction | Serializer allowlist | |
|---|---|---|
| Default for unknown fields | Logged | Dropped |
| Code to maintain | A list of paths | A function per object type |
| Failure mode | Silent leak | Missing debug context |
Allowlisting is safer, but it costs more code and will sometimes drop a field someone needs during an incident. That costs you some debugging context, which is easier to recover from than a leaked credential. Use both approaches together. Log identifiers and shapes such as counts, types and lengths rather than raw payloads, and treat any new object passed to a logger as a review item in code review.
const pino = require('pino')
const logger = pino({
// Denylist backstop: catches known secret paths if they slip through
redact: {
paths: ['headers.authorization', 'headers.cookie', '*.password'],
censor: '[REDACTED]'
},
// Allowlist: serializers run per top-level key and return only chosen fields
serializers: {
err: pino.stdSerializers.err, // type, message, stack (message is NOT scrubbed)
// Fields added to the user object later are dropped, not logged
user: (u) => ({ id: u.id, role: u.role }),
// Large payload: log identifiers and shape, not contents
order: (o) => ({
id: o.id,
itemCount: Array.isArray(o.items) ? o.items.length : 0,
currency: o.currency
}),
// Strip the query string and keep a single safe header
req: (req) => ({
method: req.method,
path: typeof req.url === 'string' ? req.url.split('?')[0] : undefined,
requestId: req.headers && req.headers['x-request-id']
})
}
})
const user = { id: 'u_123', role: 'admin', email: 'a@example.com', accessToken: 'tok_placeholder' }
const order = { id: 'ord_42', currency: 'EUR', items: [{ sku: 'A1' }, { sku: 'B2' }] }
// Logs { user: { id, role }, order: { id, itemCount: 2, currency } }
// email and accessToken never reach the output
logger.info({ user, order }, 'order placed')
// Child loggers inherit the same serializers and redaction
const reqLog = logger.child({ requestId: 'req-7f3a' })
reqLog.info({ user }, 'loaded user')
// Neither mechanism inspects the message string: avoid this
// logger.info(`token=${user.accessToken}`)
Shows serializer-based allowlisting for user, order and req objects, with path redaction kept as a backstop and a note that message strings are never scrubbed.
How do child loggers carry a log correlation id through a request?
A child logger is created with logger.child(bindings). It returns a new logger that adds those key-value pairs to every line it writes, while sharing the parent's destination and configuration. Build the hierarchy deliberately. The root logger binds service once at startup. Each module creates a child with module. Per-request children add requestId and tenantId. With this setup, a query in your log backend can filter on any of these fields without parsing message strings.
Per-request handling
Assign the request ID at the trust boundary, before any handler code runs:
- Read the inbound header, conventionally
x-request-id. - Validate the format and length. Accept only a restricted character set, such as alphanumerics, hyphens and underscores, up to a fixed maximum such as 128 characters. The header comes from the client, so an unvalidated value can inject newlines or fake fields into downstream text logs, or inflate every line with kilobytes of junk.
- Generate a replacement if the value is missing or fails validation. Use
crypto.randomUUID()fromnode:crypto. - Echo the ID in the response header so clients and support staff can quote it when reporting a problem.
- Create the child logger with
requestIdandtenantId, and attach it to the request object.
Keep bindings small
Pino serializes bindings when the child is created, then writes them on every line. A large binding, such as a full user record or the request headers, adds allocations on each request and repeats the same bytes in every log entry. That increases log volume and ingestion cost. It can also bring back the field-leak risk that redaction was meant to remove. Bind identifiers, not whole objects.
import http from 'node:http';
import { randomUUID } from 'node:crypto';
import pino from 'pino';
// Root logger binds the service name once at startup.
const logger = pino({ base: { service: 'billing-api' } });
// Module-level child: every line from this file carries module=http.
const log = logger.child({ module: 'http' });
// Trust boundary: allow only a safe character set, capped at 128 chars.
const REQUEST_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
function resolveRequestId(req) {
const inbound = req.headers['x-request-id'];
// Reuse a valid client value; otherwise generate a fresh one.
return typeof inbound === 'string' && REQUEST_ID_RE.test(inbound)
? inbound
: randomUUID();
}
const server = http.createServer((req, res) => {
const requestId = resolveRequestId(req);
// Echo the ID so clients and support staff can quote it.
res.setHeader('x-request-id', requestId);
// Placeholder: derive the tenant from authenticated context, not a raw header.
const tenantId = 'tenant-0042';
// Bind identifiers only. Never bind the user record or req.headers.
req.log = log.child({ requestId, tenantId });
req.log.info({ method: req.method, url: req.url }, 'request received');
res.end('ok');
req.log.info({ statusCode: res.statusCode }, 'request completed');
});
server.listen(3000);
A plain node:http server that validates or generates an x-request-id at the trust boundary, echoes it in the response, and binds it with the tenant ID into a per-request Pino child logger beneath service- and module-level bindings.
How do you propagate the correlation id across layers and services?
There are two ways to get the request-scoped child logger into deeper layers.
| Approach | Coupling | Overhead | Failure mode |
|---|---|---|---|
| Pass the logger explicitly as an argument | Visible in every function signature | None beyond the extra parameter | Verbose; a forgotten argument falls back to the root logger |
Retrieve it from AsyncLocalStorage |
Implicit; any function can depend on hidden ambient state | Small per-async-operation tracking cost | Context silently disappears and entries lose the id |
Explicit passing is noisy, but a type checker or code review will catch a missing logger. AsyncLocalStorage keeps signatures clean, but it creates a hidden dependency on the request context. That dependency breaks without any error. Callback-based libraries and pooled resources such as database connection pools, worker pools and some older clients can run callbacks under the async context of whichever caller created the pooled resource. When that happens, a deep log line may carry no id or the wrong request's id. Do not assume propagation works. Write a test that fires two concurrent requests through each driver you use and asserts that every log line carries the correct id.
Logs inside the process are only part of the job. Each outbound hop must also forward the id. Set it as a header on HTTP calls, such as x-request-id or a W3C traceparent. Write it into message headers or attributes when publishing to a queue. On the receiving side, the consumer reads the id from the message and creates its own child logger, the same way the HTTP handler does.
The id flows through the system like this:
Proxy (generates or accepts x-request-id) → Service A (child logger binds the id) → outbound HTTP header → Service B (child logger binds the same id) → message header → Queue consumer (child logger binds the id per message)
How can you test redaction in CI so regressions don't reach production?
Build the test logger from the same options module your application imports, not a copy of the redaction paths. Pino accepts any writable stream as its second argument, so pass a small Writable that pushes each chunk into an array. Then log realistic payloads seeded with sentinel secrets, such as a password of SENTINEL_PW_7f3a or a bearer token of SENTINEL_TOKEN_91c2. Bind a known correlation id on a child logger before logging.
Assert against the raw serialized output, not parsed fields. A substring check for each sentinel catches the secret wherever it lands: nested under a renamed key, inside an error's message, or concatenated into a string. Separately, assert that every line contains the correlation id. This confirms that redaction did not strip or break the bindings you rely on for tracing.
Build the payloads with the same factories or fixtures your handlers use. When someone renames password to passphrase in the request type, the fixture changes with it, the path-based rule no longer matches, and the sentinel appears in the output. The build fails on that pull request. Because the test also imports the production options, someone who edits the redaction list for one service without updating shared config triggers the same failure.
Illustrative estimate. These inputs are assumptions, not measurements:
- Writing the tests takes about 4 engineer-hours.
- Maintaining them takes about 1 hour per quarter.
- A single leak found in production takes about 30 engineer-hours. That covers scoping affected log stores, purging or restricting retained logs, rotating credentials, and writing the incident review.
Under those assumptions, preventing one leak covers several years of upkeep. The cost of the incident also falls on whoever is on call, rather than on the author of the change.
How can this setup save engineering time?
The savings come from moving repeated, error-prone work out of individual call sites and incident investigations and into configuration that is written once.
- Faster incident triage. With a
requestIdon every line in every service, reconstructing one failing request is a single filter query in the log backend instead of correlating timestamps across hosts and grepping free text. Support staff can quote the id from the response header, so engineers start from the exact request rather than a time window. - Fewer format-specific parsers. NDJSON with consistent field names means dashboards, alerts and ad-hoc queries work on fields directly. Nobody has to maintain regexes that break when someone rewords a log message.
- Less review effort per log call. Redaction paths and serializers live in one shared options module. Reviewers check that module and the CI test rather than auditing every
logger.info()for secrets, and individual developers don't have to remember which headers are sensitive. - Less debugging by redeploy. Because the level can be changed at runtime on a single child logger, you can raise one subsystem to
debugto investigate a problem instead of adding log lines, shipping a build and waiting for the issue to recur. - Avoided leak cleanup. As the estimate in the previous section shows, a regression caught in CI is far cheaper than purging logs and rotating credentials after the fact.
Illustrative estimate. These inputs are assumptions, not measurements: a team handles 4 production incidents per month, and on each one an engineer spends about 45 minutes correlating unstructured logs across services by timestamp and text search. With a propagated correlation id, assume that step drops to about 10 minutes. That saves roughly 35 minutes per incident, or a little over 2 engineer-hours per month, before counting the review and cleanup savings above. Substitute your own incident rate and investigation times; the shape of the calculation matters more than these particular numbers.
Who should use this setup?
This approach fits teams where logs are read by machines first and people second:
- Backend and platform teams running Node.js services in production, especially where several services or queue consumers handle one user action and logs flow into a central store.
- Services that handle credentials, tokens or personal data, where a leaked header or field in retained logs becomes a security or compliance problem. Redaction plus serializer allowlisting, enforced by a CI test, gives you a reviewable control rather than relying on each developer's care.
- High-throughput APIs and workers where logging overhead on the event loop matters, and where keeping formatting and shipping off the main thread has a real effect on latency.
- Teams with on-call rotations who need to go from a customer report or alert to the relevant log lines quickly.
It is less useful for the cases listed in the next section, such as short-lived scripts or environments where the platform already handles scrubbing and trace injection.
Which operational settings matter in production, and when should you avoid this setup?
Set the level per environment from configuration rather than code: debug locally, info in production, and warn for high-volume paths if ingest cost matters. The level property can be reassigned at runtime on the root logger or on a single child. Raising one child to debug lets you inspect a single subsystem or tenant without flooding the whole pipeline, as long as you expose that switch behind an authenticated admin route or a signal handler.
The last lines before a crash are usually the most useful, and they are also the ones most likely to be lost. On fatal errors and on SIGTERM, log the event, call the logger's flush method, and exit only after it completes. An OOM kill or SIGKILL gives you no chance to do this, which is why the destination you choose matters.
| Destination | Hot-path latency | Crash or OOM-kill risk |
|---|---|---|
| Synchronous write to stdout or a file | Higher; each line blocks the event loop briefly | Lines already logged are written |
| Asynchronous, buffered destination | Low | The unflushed buffer is lost |
| Worker-thread transport | Lowest on the main thread | Lines queued for the worker are lost |
The setup costs a few days to build: redaction paths, correlation middleware, and CI tests. After that, upkeep is small. That is usually cheaper than investigating one incident from flat, uncorrelated text.
Skip or simplify this setup in three cases:
- Short-lived scripts. Plain synchronous logging is enough.
- Services that touch no credentials or personal data. Redaction adds little here.
- Platforms whose log pipeline already scrubs fields and injects trace IDs. Duplicating that work creates two sources of truth that can drift apart.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to pino structured logging, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.