skip to content

With morgan, how do you add a request id to every access-log line, and when do you need morgan.token rather than the built-in :req[header] token?

level: middleimportance: must knowfreq 30%

answer

  1. header in, or generated in-app
  2. a token reads req and res
  3. registered once, process-wide
  4. missing values print a dash

basics

~20 s

If the id arrives in a request header, the built-in :req[x-request-id] token prints it. If your code generates the id and stores it on req, register morgan.token('id', (req) => req.id) once and put :id in the format string.

solid answer

~40 s

A token is a function of `(req, res)` that returns a string. When an upstream proxy already sends the id, `:req[x-request-id]` prints that request header (the name is lowercased, so capitalisation does not matter), and `:res[x-request-id]` prints it if the app echoes it back. When the app generates the id itself, say in middleware that sets `req.id`, register `morgan.token('id', (req) => req.id)` and use `:id`. `morgan.token` writes onto the shared morgan module, so it is process-wide: every logger sees the token, and reusing a name, even a built-in like `url`, overwrites it. A missing value prints `-` in a format string. A misspelt token name is not caught at startup: the first request throws a `TypeError` when its line is formatted.

code

javascript · 14 lines
javascript
const crypto = require('node:crypto')
const express = require('express')
const morgan = require('morgan')

morgan.token('id', (req) => req.id)

const app = express()
app.use((req, res, next) => {
  req.id = req.get('x-request-id') || crypto.randomUUID()
  res.set('X-Request-Id', req.id)
  next()
})
app.use(morgan(':id :method :url :status :response-time ms'))
app.get('/orders', (req, res) => res.json([]))

go deeper

for a junior

Know that :req[x-request-id] prints a request header and that morgan.token defines your own :name token from req and res.

for a middle

Explain when the id needs a custom token, that tokens are process-wide and overwrite by name, and that empty values print a dash.

for a senior

Diagnose a dash where the id should be, a typo that only fails on the first request, and an id read before the code that sets it.

for a principal

Decide where request ids are minted and how the access line carries them, so every service in the team's estate can be traced the same way.

## Why the access line needs the id A **request id** (or correlation id) is a short unique value attached to one HTTP request so that every log entry produced while serving it can be joined later. The access line morgan writes is often the only entry for a fast, successful request, so if it lacks the id, the request cannot be followed from the edge to the application. None of morgan's predefined formats include one; you add it to a format string or a format function. ## Two sources, two tokens Where the id comes from decides which token you need: | Where the id lives | Token | Needs `morgan.token`? | |---|---|---| | A request header set by a proxy or the calling service | `:req[x-request-id]` | No | | A response header the app sets | `:res[x-request-id]` | No | | A property the app sets on `req`, such as `req.id` | a custom token, e.g. `:id` | Yes | The two built-in header tokens behave slightly differently: - `:req[header]` reads `req.headers[name.toLowerCase()]`, so `:req[X-Request-Id]` and `:req[x-request-id]` are the same. A header sent several times is joined with `, `. - `:res[header]` reads `res.getHeader(name)`, but only once the headers have been sent; before that it has no value. Generating the id in the application is the more common case, because many requests arrive without one. Then a custom token is the way to expose it. ## How morgan.token works `morgan.token(name, fn)` registers a token. Key facts: - **The callback receives `(req, res)`** and should return a string. Extra arguments come from square brackets, so `:id[short]` would call `fn(req, res, 'short')`. - **It is process-wide.** The function is stored on the morgan module itself, and every compiled format looks tokens up there when it formats a line. A token registered anywhere is visible to every morgan logger in the process, including ones created earlier. - **A repeated name overwrites.** Calling `morgan.token('url', fn)` replaces the built-in `:url` for every logger. Pick names that cannot collide, such as `id` or `request-id`. - **Names need at least two characters.** The format-string parser matches `:` followed by two or more letters, digits, underscores or hyphens, so a one-character name such as `:x` is printed literally rather than replaced. ## When the token is evaluated Tokens run when the line is formatted, which by default is when the response **finishes**. So the code that sets `req.id` only has to run before the response completes. With `immediate: true` the line is formatted as soon as the request reaches morgan, and the id must already be on `req` by then or the token prints `-`. ## What goes wrong 1. **A missing value** prints `-` in a format string, because the compiled string substitutes a dash for any empty token. A format function gets the raw `undefined` instead and must handle it. 2. **A typo in the format string**, such as `:requestid` when only `id` was registered, is not detected when `morgan()` is called. The first request fails with `TypeError: tokens.requestid is not a function` when its line is formatted, after the response has been sent, and the error escapes as an uncaught exception. 3. **An unvalidated client header** used as the id lets callers choose what appears in your logs, so cap the length and check the format of an incoming id before trusting it. ## Doing it with a format function A format string is not the only way in. When the format is a function `(tokens, req, res)`, the id can be read straight from the request: - `return [req.id, tokens.method(req, res), tokens.url(req, res), tokens.status(req, res)].join(' ')` needs no registered token at all, so nothing is added to the shared namespace. - The built-in tokens are still available on `tokens`, called with `(req, res)` and any argument, for example `tokens.req(req, res, 'x-request-id')`. - The dash substitution does not apply: an id that is missing is `undefined`, and `join` turns it into an empty field unless you supply a fallback such as `req.id || '-'`. This style suits teams that keep all access-log fields in one shared function, and it is the starting point for structured entries. ## Putting it together Register the token once at module load, set the id in a small middleware that also echoes it in a response header, and reference it in the format string. Reading `req.id` in a format function works just as well and avoids the shared token namespace altogether.

  • Why might a request-id token print a dash even though the id middleware exists?
    Either the token returned `undefined` because the property name differs (`req.id` versus `req.requestId`), or the logger uses `immediate: true` and formats the line before the id middleware has run. Without `immediate`, tokens run when the response finishes, so the id only has to be set before then.
  • What happens if two parts of a codebase both call morgan.token('id', ...)?
    The second call silently replaces the first for every morgan logger in the process, because tokens live on the shared morgan module. Whichever module loads last wins, which can make access lines change after an unrelated import. Register shared tokens in one place.

  • morgan.token only affects the logger created right after the call.
  • The :req[header] token needs the header name in the exact case the client sent.
  • A missing request id leaves an empty gap in a format-string line.
  • A misspelt token name in the format string fails when the app starts.
  • Registering a token named url adds a second url token beside the built-in one.