pino-http

library11.0.0jsnpmunverified

pino-http is a high-speed HTTP logger middleware designed for Node.js applications, leveraging the highly performant Pino logging library. It focuses on providing structured JSON logs for HTTP requests and responses with minimal overhead, making it ideal for high-throughput microservices and APIs. The package is currently at version 11.0.0 and follows a release cadence that often aligns with major updates to its underlying `pino` dependency, typically seeing several minor/patch releases throughout the year. Its primary differentiator is its exceptional performance compared to other HTTP loggers, achieved by deferring heavy log processing. It provides extensive customization options for log levels, request ID generation, and structured log data.

observability http-networking web-framework

npm install pino-http

github ↗package ↗

INSTALL

IMPORT

SIG · PINO-HTTP

pino-http

observabilityjavascriptv11.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pinoHttp

✓ import pinoHttp from 'pino-http'; // or import createPinoHttp from 'pino-http';

✗ const pinoHttp = require('pino-http'); // Requires a function call to initialize: const pinoHttp = require('pino-http')();

The default export is a factory function. In CommonJS, `require('pino-http')()` is typically used. For ESM, `import pinoHttp from 'pino-http';` or `import createPinoHttp from 'pino-http';` followed by `pinoHttp()` or `createPinoHttp()` to instantiate.

PinoHttpLogger

✓ import type { PinoHttpLogger } from 'pino-http';

Type import for the instantiated logger function provided by pino-http. Use for explicit TypeScript typing.

PinoLogger

✓ import type { Logger as PinoLogger } from 'pino';

The `req.log` property injected by pino-http is a standard Pino logger instance. For full type coverage, import `Logger` from 'pino' and alias it if necessary.

This quickstart demonstrates how to set up `pino-http` with a custom base logger, request ID generation, and dynamic log level based on response status. It includes a basic HTTP server, showcasing how `req.log` is injected for contextual logging and how to use `pino-pretty` for development output.

import http from 'node:http'; import pinoHttp from 'pino-http'; import pino from 'pino'; // Create a base Pino logger (optional, pino-http can create one internally) const baseLogger = pino({ level: process.env.NODE_ENV === 'production' ? 'info' : 'debug', transport: { target: 'pino-pretty', options: { colorize: true } } }); const loggerMiddleware = pinoHttp({ logger: baseLogger, genReqId: function (req) { // Generate a unique request ID for better traceability return req.headers['x-request-id'] || Math.random().toString(36).substring(2, 15); }, customLogLevel: function (req, res, err) { if (res.statusCode >= 400 && res.statusCode < 500) return 'warn'; if (res.statusCode >= 500 || err) return 'error'; return 'info'; } }); const server = http.createServer((req, res) => { loggerMiddleware(req, res); req.log.info({ url: req.url, method: req.method }, 'Incoming request'); if (req.url === '/error') { req.log.error('Simulating an error'); res.statusCode = 500; res.end('Internal Server Error'); return; } res.end('Hello world!'); }); const PORT = process.env.PORT || 3000; server.listen(PORT, () => { baseLogger.info(`Server listening on port ${PORT}`); }); // To run: node --loader ts-node/esm your-file.ts (if using ts-node and ESM) // or: node your-file.js

Debug

Known issues

breakingpino-http v11.x, which updates to pino v10.x, officially drops support for Node.js 18. Users on Node.js 18 or older should use pino-http v10.x or upgrade their Node.js version.

fix

Upgrade Node.js to version 20 or higher. If upgrading is not immediately possible, pin pino-http to a `^10.0.0` version.

affects: >=11.0.0

gotchaThe `customLogLevel` and `useLevel` options are mutually exclusive. Providing both will result in undefined behavior or one overriding the other in an unexpected way.

fix

Choose either `customLogLevel` (a function for dynamic level selection) or `useLevel` (a static level string) but not both.

affects: >=1.0.0

gotchaBy default, `pino-http` automatically logs a 'request completed' or 'request errored' message. To disable this, set `autoLogging: false` in the options. To selectively ignore certain requests from being logged, use `autoLogging.ignore`.

fix

Set `autoLogging: false` to disable automatic logging entirely, or `autoLogging: { ignore: (req) => req.url === '/healthz' }` for conditional exclusion.

affects: >=1.0.0

gotchaLogging sensitive request bodies or adding extensive custom serializers can negatively impact performance and introduce security risks by exposing private data.

fix

Carefully consider what data is serialized. Use Pino's redaction capabilities or custom serializers to remove sensitive information. Avoid logging large request bodies unless absolutely necessary.

affects: >=1.0.0

gotchaThe default `genReqId` (request ID generator) uses an integer counter which might not be unique across multiple application instances or restarts. For robust production environments, a more unique ID generation strategy is recommended.

fix

Provide a custom `genReqId` function that generates truly unique IDs, e.g., using `uuid` or a tracing ID from upstream services (`req.headers['x-request-id']`).

affects: >=1.0.0

Errors

Common errors & fixes

logs are not formatted/colored, they are raw JSON

`pino-pretty` is not installed or not used in the transport configuration.

fix

Install `pino-pretty` (`npm i -D pino-pretty`) and configure Pino's `transport` option, typically only for development environments, to use it.

Error: Cannot find module 'pino-http' or type errors related to `pinoHttp` not being a function

Incorrect CommonJS `require` usage or improper ESM import for the factory function.

fix

For CommonJS, ensure `const pinoHttp = require('pino-http')();` (with `()`). For ESM, use `import pinoHttp from 'pino-http';` then call it as `pinoHttp();`.

TypeError: Cannot read properties of undefined (reading 'info') on req.log

`pino-http` middleware function was not called or executed for the given request/response cycle, or was called incorrectly.

fix

Ensure `loggerMiddleware(req, res);` (where `loggerMiddleware` is your `pinoHttp()` instance) is called early in your HTTP request handling chain, typically as the first middleware in frameworks like Express.

Argument of type 'string' is not assignable to parameter of type 'PinoLogLevel'.

Using a custom log level string that is not recognized by Pino's default types or declared in your custom levels.

fix

Ensure that custom log levels are correctly defined in your Pino configuration via the `customLevels` option and that the `useLevel` or `customLogLevel` functions return one of these defined levels or standard Pino levels.

Upgrade

Version history

11.0.0latest on npm

Audit

Dependencies

pinorequiredCore logging library that pino-http is built upon for high-speed, structured logging. Version compatibility is critical for major updates.

pino-prettyoptionalUsed for human-readable, colored output during development. Not a runtime dependency for production applications but essential for local debugging.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pinojs/pino-http ↗

packagehttps://www.npmjs.com/package/pino-http ↗