Logging with pino
A server's logs are how you find out what happened after it happened, so pino writes each event as one JSON line with a level, pino-http adds a line for every request, redact hides tokens and passwords, and pino-pretty makes the lines readable while you develop.
Journeyman · Node.js · Web Development · Updated
After this lesson you can
- Write structured JSON logs with pino at the right level, such as info, warn or error, and choose the level that's logged
- Log every request with pino-http, redact secrets such as the Authorization header, and use pino-pretty only while developing
Key takeaways
- console.log on a server gives lines with no time, no level and no request, so a problem from last night can't be found or filtered.
- pino writes each log as one line of JSON, with a level, a time and any fields you add, so tools can search and filter it.
- The levels run from trace and debug up through info, warn and error to fatal. A logger set to warn writes warn and above and skips the rest.
- pino-http is middleware that logs every request with its method, URL, status code and response time, and gives each route req.log.
- A log must never hold a token or password. pino's redact option writes [Redacted] in their place, and pino-pretty is for reading logs on your own computer only.
Once your API is online, you can't watch its terminal. When a rider says "the shuttle app showed no buses at 7:40 this morning", the server's logs are the only witness. Every team you join will have a log search, and the first question in any incident is "what do the logs say?"
The Campus Shuttle API answers riders with routes, stops and arrival times. So far it reports what it's doing with console.log:
console.log("Shuttle API started");
console.log("GET /routes/night-owl");
console.log("No buses for night-owl");
Shuttle API started
GET /routes/night-owl
No buses for night-owl
On your laptop that's fine. On a server answering hundreds of riders, these lines have no time, so you can't find 7:40. They have no level, so a real problem looks the same as a routine one. And they're loose text, so a tool can't ask for "only the errors about the Night Owl".
One JSON line per event: pino
Think of a ship's logbook: every entry has the time, how serious it is, and the facts, always in the same places, so anyone can scan it later. Structured logging is that idea for programs: each log is a record with named fields instead of a sentence. pino (read "PEE-no") is the logger most Node APIs use for it. Install it with npm install pino, then:
import pino from "pino";
const logger = pino();
logger.info("The Campus Shuttle API is starting");
logger.warn({ route: "night-owl" }, "The Night Owl has no buses tonight");
logger.error({ stop: "stadium" }, "No arrival times for this stop");
{"level":30,"time":1794939191781,"pid":243928,"hostname":"sams-laptop","msg":"The Campus Shuttle API is starting"}
{"level":40,"time":1794939191782,"pid":243928,"hostname":"sams-laptop","route":"night-owl","msg":"The Night Owl has no buses tonight"}
{"level":50,"time":1794939191782,"pid":243928,"hostname":"sams-laptop","stop":"stadium","msg":"No arrival times for this stop"}
Each line is one JSON object: the level as a number, the time in milliseconds since 1970, the process id, the computer's name, your own fields (route, stop), and the message in msg. Your times and ids will differ. The object goes first and the message second.
Levels: how serious is it?
A log level says how much a line matters. pino has six, each with a number:
| Level | Number | Use it for |
|---|---|---|
trace |
10 | Every small step, when you're hunting one bug |
debug |
20 | Details that help while developing |
info |
30 | Normal events: started, a request answered |
warn |
40 | Something odd that the API survived |
error |
50 | Something failed |
fatal |
60 | The API can't go on |
A logger writes its own level and everything above it. pino({ level: "warn" }) writes warn, error and fatal, and skips info and below. pino's own default is info. Reading the level from a setting lets you turn on debug lines while you hunt a problem, and turn them off again without changing code:
const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
A line for every request: pino-http
Writing logger.info in every route gets old. pino-http (npm install pino-http) is middleware, like the ones in Middleware: Code That Runs on Every Request: put it before your routes, and it logs one line for every request when its answer is sent. It also gives each route req.log, a logger that adds the request to every line:
const app = express();
app.use(pinoHttp({ logger }));
app.get("/routes", (req, res) => {
req.log.debug({ count: routes.length }, "Sending every route");
res.json(routes);
});
Send GET http://localhost:3100/routes with the header Authorization: Bearer test-token-for-the-lesson (this run sent it with Node's own fetch, so the user-agent is node), and the terminal gets one line:
{"level":30,"time":1794939201938,"pid":199308,"hostname":"sams-laptop","req":{"id":1,"method":"GET","url":"/routes","query":{},"params":{},"headers":{"host":"localhost:3100","connection":"keep-alive","authorization":"Bearer test-token-for-the-lesson","accept":"*/*","accept-language":"*","sec-fetch-mode":"cors","user-agent":"node","accept-encoding":"gzip, deflate"},"remoteAddress":"::1","remotePort":64496},"res":{"statusCode":200,"headers":{"x-powered-by":"Express","content-type":"application/json; charset=utf-8","content-length":"99","etag":"W/\"63-iMbHE26hrwLBK49JJrhV2PyKMtE\""}},"responseTime":4,"msg":"request completed"}
The method, the URL, the status code and responseTime, 4 milliseconds, are all there. So is the rider's token.
Never log a secret: redact
Logs are read by more people than your code is, and they're kept for months. A token in a log lets anyone who reads it act as that rider; Keeping Secrets Out of Your Code explains why that's serious. pino's redact option takes paths to the fields to hide, and writes [Redacted] in their place, which is called log redaction:
const logger = pino({
level: process.env.LOG_LEVEL ?? "info",
redact: ["req.headers.authorization", "req.headers.cookie"],
});
Send the same request, and the line now holds "authorization":"[Redacted]". Redact passwords the same way, wherever they could appear in a field you log, such as a database address.
Readable logs while you develop: pino-pretty
JSON lines suit a log search, not your eyes. pino-pretty (npm install --save-dev pino-pretty) reads them and prints each one in color. A pipe, | (read "pipe"), hands one program's output to the next, in PowerShell and zsh alike:
node server.js | npx pino-pretty
Its first lines, with LOG_LEVEL=debug:
[11:13:36.303] INFO (240932): The Campus Shuttle API is listening on http://localhost:3100
[11:13:38.287] DEBUG (240932): Sending every route
Each line's fields follow it, one per line, with the token still [Redacted]. Keep pino-pretty for your own computer: a host's log search wants the plain JSON, so npm start stays node server.js, and only your development script pipes through pino-pretty.
Check yourself
2 questions to try on the lesson page.
So what
One JSON line per event, at the right level, with every request logged and every secret redacted, turns "the app showed no buses this morning" into a search that finds the exact request in seconds.