Bunyan HTTP Middleware Logger

1.0.2 · active · verified Wed Apr 22

bunyan-middleware is a Node.js middleware for logging HTTP requests and responses using the Bunyan logger. Currently at version 1.0.2, it appears to be a stable project, though its release cadence is not explicitly stated. This library offers robust features for integrating structured logging into Express, Connect, or pure HTTP servers. Key differentiators include automatic management of the `X-Request-Id` header (generating a UUID if not present), logging request-response duration, providing a request-scoped logger (`req.log`) for tracing individual requests throughout an application, and custom serializers for `req` and `res` objects. It also provides functionality to obscure sensitive headers in log outputs, enhancing security and compliance. It is a direct dependency of an existing Bunyan logger instance, allowing for consistent logging configuration.

Common errors

```
TypeError: bunyanMiddleware is not a function
```
cause Attempting to use `import bunyanMiddleware from 'bunyan-middleware'` in an ESM context without proper CommonJS interoperability configuration, leading to the module object being imported instead of the default export function.

fix In TypeScript or CommonJS, use `const bunyanMiddleware = require('bunyan-middleware')`. If forced to use ESM `import` in a modern Node.js environment, ensure your `tsconfig.json` or bundler settings handle CommonJS imports correctly, or wrap `require` in a utility function.
```
Sensitive headers (e.g., Authorization, Cookie) are appearing in logs despite `obscureHeaders` being configured.
```
cause The `obscureHeaders` option is case-sensitive or not configured correctly, or the headers are being logged by other means before `bunyan-middleware` processes them.

fix Verify that the header names in the `obscureHeaders` array exactly match the casing of the incoming HTTP headers. Double-check that `bunyan-middleware` is applied early in your middleware stack to obscure headers before other logging mechanisms capture them.

Warnings

gotcha This package is distributed as a CommonJS module. In modern TypeScript or pure ESM projects, a direct `import bunyanMiddleware from 'bunyan-middleware'` will likely fail or require specific bundler configurations. The recommended TypeScript import is `import bunyanMiddleware = require('bunyan-middleware')`.
Fix: For TypeScript, use `import bunyanMiddleware = require('bunyan-middleware')`. For ESM-only JavaScript, consider using a CommonJS wrapper or a bundler that correctly handles CommonJS modules.
gotcha The `logger` option is a required configuration. Failing to provide a valid Bunyan logger instance will result in runtime errors as the middleware attempts to use it.
Fix: Always pass an initialized Bunyan logger instance to the `bunyanMiddleware` options, e.g., `logger: bunyan.createLogger({ name: 'my-app' })`.
gotcha When using `bunyan-middleware` with Express mounted apps that rewrite `req.url`, the default Bunyan `req` serializer might log the rewritten URL instead of the original. `bunyan-middleware` provides its own serializer using `req.originalUrl` to mitigate this, but custom serializer overrides could reintroduce this behavior.
Fix: Ensure that if you provide custom `req` serializers, they correctly reference `req.originalUrl` or the desired URL property for accurate logging in mounted Express applications.

Install

npm install bunyan-middleware npm
yarn add bunyan-middleware yarn
pnpm add bunyan-middleware pnpm

Imports

bunyanMiddleware
wrong:
```
import bunyanMiddleware from 'bunyan-middleware'
```
correct:
```
const bunyanMiddleware = require('bunyan-middleware')
```
This package is distributed as a CommonJS module. For TypeScript, use `import bunyanMiddleware = require('bunyan-middleware')`. For ESM projects, direct `import` syntax might require bundler configuration or a CommonJS wrapper.

BunyanMiddlewareOptions

import bunyanMiddleware = require('bunyan-middleware');
type Options = bunyanMiddleware.BunyanMiddlewareOptions;

TypeScript types are nested under the main `bunyanMiddleware` export.

Quickstart

This example demonstrates setting up bunyan-middleware with Express, configuring request ID handling, obscuring headers, adding custom finish data, and utilizing the request-scoped `req.log`.

const bunyan = require('bunyan')
const bunyanMiddleware = require('bunyan-middleware')
const express = require('express')

const app = express()
const logger = bunyan.createLogger({ name: 'My App', level: process.env.LOG_LEVEL || 'info' })

app.use(bunyanMiddleware(
    { headerName: 'X-Request-Id'
    , propertyName: 'reqId'
    , logName: 'req_id'
    , obscureHeaders: ['authorization', 'cookie'] // Example: obscure sensitive headers
    , logger: logger
    , additionalRequestFinishData: function(req, res) {
        // Add custom data to the 'request finish' log message
        return { exampleCustomData: 'value' }
      }
    }
  )
)

app.get('/', function (req, res) {
  // Use `req.log` for request-specific logging, automatically including the request ID.
  req.log.info({ user: 'guest' }, 'Accessed home route')
  res.send('Hello, Bunyan Logger!')
})

const port = process.env.PORT || 3000;
app.listen(port, () => {
  logger.info(`Server listening on port ${port}`);
});

view raw JSON →