pinojs/pino-http pinojs/pino-http

  • Stars
    star
    535
  • Rank 82,940 (Top 2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 8 years ago
  • Updated 4 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
pinojs/pino-http
github

pinojs

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🌲 high-speed HTTP logger for Node.js

pino-httpΒ Β Build Status

High-speed HTTP logger for Node.js

To our knowledge, pino-http is the fastest HTTP logger in town.

Benchmarks

Benchmarks log each request/response pair while returning 'hello world', using autocannon with 100 connections and 10 pipelined requests.

  • http-ndjson (equivalent info): 7730.73 req/sec
  • http-ndjson (standard minimum info): 9522.37 req/sec
  • pino-http: 21496 req/sec
  • pino-http (extreme): 25770.91 req/sec
  • no logger: 46139.64 req/sec

All benchmarks where taken on a Macbook Pro 2013 (2.6GHZ i7, 16GB of RAM).

Install

npm i pino-http --save

Example

'use strict'

const http = require('http')
const server = http.createServer(handle)

const logger = require('pino-http')()

function handle (req, res) {
  logger(req, res)
  req.log.info('something else')
  res.end('hello world')
}

server.listen(3000)
$ node example.js | pino-pretty
[2016-03-31T16:53:21.079Z] INFO (46316 on MBP-di-Matteo): something else
    req: {
      "id": 1,
      "method": "GET",
      "url": "/",
      "headers": {
        "host": "localhost:3000",
        "user-agent": "curl/7.43.0",
        "accept": "*/*"
      },
      "remoteAddress": "::1",
      "remotePort": 64386
    }
[2016-03-31T16:53:21.087Z] INFO (46316 on MBP-di-Matteo): request completed
    res: {
      "statusCode": 200,
      "header": "HTTP/1.1 200 OK\r\nX-Powered-By: restify\r\nContent-Type: text/html; charset=utf-8\r\nContent-Length: 11\r\nETag: W/\"b-XrY7u+Ae7tCTyyK7j1rNww\"\r\nDate: Thu, 31 Mar 2016 16:53:21 GMT\r\nConnection: keep-alive\r\n\r\n"
    }
    responseTime: 10
    req: {
      "id": 1,
      "method": "GET",
      "url": "/",
      "headers": {
        "host": "localhost:3000",
        "user-agent": "curl/7.43.0",
        "accept": "*/*"
      },
      "remoteAddress": "::1",
      "remotePort": 64386
    }

API

pinoHttp([opts], [stream])

opts: it has all the options as pino and

  • logger: parent pino instance for a child logger instance, which will be used by pino-http. To refer to this child instance, use pinoHttp.logger
  • genReqId: you can pass a function which gets used to generate a request id. The first argument is the request itself. As fallback pino-http is just using an integer. This default might not be the desired behavior if you're running multiple instances of the app
  • useLevel: the logger level pino-http is using to log out the response. default: info
  • customLogLevel: set to a function (req, res, err) => { /* returns level name string */ }. This function will be invoked to determine the level at which the log should be issued (silent will prevent logging). This option is mutually exclusive with the useLevel option. The first two arguments are the HTTP request and response. The third argument is an error object if an error has occurred in the request.
  • autoLogging: set to false, to disable the automatic "request completed" and "request errored" logging. Defaults to true. If set to an object, you can provide more options.
  • autoLogging.ignore: set to a function (req) => { /* returns boolean */ }. Useful for defining logic based on req properties (such as a user-agent header) to ignore successful requests.
  • stream: same as the second parameter
  • customReceivedMessage: set to a function (req, res) => { /* returns message string */ } This function will be invoked at each request received, setting "msg" property to returned string. If not set, nothing value will be used.
  • customReceivedObject: set to a function (req, res, loggableObject) => { /* returns loggable object */ } This function will be invoked at each request received, replacing the base loggable received object. When set, it is up to the reponsibility of the caller to merge with the loggableObject parameter. If not set, default value will be used.
  • customSuccessMessage: set to a function (req, res) => { /* returns message string */ } This function will be invoked at each successful response, setting "msg" property to returned string. If not set, default value will be used.
  • customSuccessObject: set to a function (req, res, loggableObject) => { /* returns loggable object */ } This function will be invoked at each successful response, replacing the base loggable success object. When set, it is up to the reponsibility of the caller to merge with the loggableObject parameter. If not set, default value will be used.
  • customErrorMessage: set to a function (req, res, err) => { /* returns message string */ } This function will be invoked at each failed response, setting "msg" property to returned string. If not set, default value will be used.
  • customErrorObject: set to a function (req, res, err, loggableObject) => { /* returns loggable object */ } This function will be invoked at each failed response, the base loggable error object. When set, it is up to the reponsibility of the caller to merge with the loggableObject parameter. If not set, default value will be used.
  • customAttributeKeys: allows the log object attributes added by pino-http to be given custom keys. Accepts an object of format { [original]: [override] }. Attributes available for override are req, res, err, responseTime and, when using quietReqLogger, reqId.
  • wrapSerializers: when false, custom serializers will be passed the raw value directly. Defaults to true.
  • customProps: set to a function (req, res) => { /* returns on object */ } or { /* returns on object */ } This function will be invoked for each request with req and res where we could pass additional properties that need to be logged outside the req.
  • quietReqLogger: when true, the child logger available on req.log will no longer contain the full bindings and will now only have the request id bound at reqId (note: the autoLogging messages and the logger available on res.log will remain the same except they will also have the additional reqId property). default: false

stream: the destination stream. Could be passed in as an option too.

Examples

Use as Express middleware
const express = require('express')
const logger = require('pino-http')

const app = express()

app.use(logger())

function handle (req, res) {
  req.log.info('something else')
  res.end('hello world')
}

app.listen(3000)
Logger options
'use strict'

const http = require('http')
const server = http.createServer(handle)
const { randomUUID } = require('node:crypto')
const pino = require('pino')
const logger = require('pino-http')({
  // Reuse an existing logger instance
  logger: pino(),

  // Define a custom request id function
  genReqId: function (req, res) {
    const existingID = req.id ?? req.headers["x-request-id"]
    if (existingID) return existingID
    id = randomUUID()
    res.setHeader('X-Request-Id', id)
    return id
  },

  // Define custom serializers
  serializers: {
    err: pino.stdSerializers.err,
    req: pino.stdSerializers.req,
    res: pino.stdSerializers.res
  },

  // Set to `false` to prevent standard serializers from being wrapped.
  wrapSerializers: true,

  // Logger level is `info` by default
  useLevel: 'info',

  // Define a custom logger level
  customLogLevel: function (req, res, err) {
    if (res.statusCode >= 400 && res.statusCode < 500) {
      return 'warn'
    } else if (res.statusCode >= 500 || err) {
      return 'error'
    } else if (res.statusCode >= 300 && res.statusCode < 400) {
      return 'silent'
    }
    return 'info'
  },

  // Define a custom success message
  customSuccessMessage: function (req, res) {
    if (res.statusCode === 404) {
      return 'resource not found'
    }
    return `${req.method} completed`
  },

  // Define a custom receive message
  customReceivedMessage: function (req, res) {
    return 'request received: ' + req.method
  },

  // Define a custom error message
  customErrorMessage: function (req, res, err) {
    return 'request errored with status code: ' + res.statusCode
  },

  // Override attribute keys for the log object
  customAttributeKeys: {
    req: 'request',
    res: 'response',
    err: 'error',
    responseTime: 'timeTaken'
  },

  // Define additional custom request properties
  customProps: function (req, res) {
    return {
      customProp: req.customProp,
      // user request-scoped data is in res.locals for express applications
      customProp2: res.locals.myCustomData
    }
  }
})

function handle (req, res) {
  logger(req, res)
  req.log.info('something else')
  res.end('hello world')
}

server.listen(3000)
Structured Object Hooks

It is possible to override the default structured object with your own. The hook is provided with the pino-http base object so that you can merge in your own keys.

This is useful in scenarios where you want to augment core pino-http logger object with your own event labels.

If you simply want to change the message which is logged then check out the custom[Received|Error|Success]Message hooks e.g. customReceivedMessage

const logger = require('pino-http')({
  //... remaining config omitted for brevity
  customReceivedObject: (req, res, val) => {
    return {
      category: 'ApplicationEvent',
      eventCode: 'REQUEST_RECEIVED'
    };
  },

  customSuccessObject: (req, res, val) => {
    return {
      ...val,
      category: 'ApplicationEvent',
      eventCode:
        res.statusCode < 300
          ? 'REQUEST_PROCESSED'
          : 'REQUEST_FAILED'
    };
  },

  customErrorObject: (req, res, error, val) => {
    const store = storage.getStore();
    const formattedBaggage = convertBaggageToObject(store?.baggage);

    return {
      ...val,
      category: 'ApplicationEvent',
      eventCode: 'REQUEST_FAILED'
    };
  }

  // ...remaining config omitted for brevity
})
PinoHttp.logger (P.Logger)

The pinoHttp instance has a property logger, which references to an actual logger instance, used by pinoHttp. This instance will be a child of an instance, passed as opts.logger, or a fresh one, if no opts.logger is passed. It can be used, for example, for doing most of the things, possible to do with any pino instance, for example changing logging level in runtime, like so:

const pinoHttp = require('pinoHttp')();
pinoHttp.logger.level = 'silent';
pinoHttp.startTime (Symbol)

The pinoHttp function has a property called startTime which contains a symbol that is used to attach and reference a start time on the HTTP res object. If the function returned from pinoHttp is not the first function to be called in an HTTP servers request listener function then the responseTime key in the log output will be offset by any processing that happens before a response is logged. This can be corrected by manually attaching the start time to the res object with the pinoHttp.startTime symbol, like so:

const http = require('http')
const logger = require('pino-http')()
const someImportantThingThatHasToBeFirst = require('some-important-thing')
http.createServer((req, res) => {
  res[logger.startTime] = Date.now()
  someImportantThingThatHasToBeFirst(req, res)
  logger(req, res)
  res.end('hello world')
}).listen(3000)
Custom formatters

You can customize the format of the log output by passing a Pino transport.

const logger = require('pino-http')({
  quietReqLogger: true, // turn off the default logging output
  transport: {
    target: 'pino-http-print', // use the pino-http-print transport and its formatting output
    options: {
      destination: 1,
      all: true,
      translateTime: true
    }
  }
})

Default serializers

pinoHttp.stdSerializers.req

Generates a JSONifiable object from the HTTP request object passed to the createServer callback of Node's HTTP server.

It returns an object in the form:

{
  pid: 93535,
  hostname: 'your host',
  level: 30,
  msg: 'my request',
  time: '2016-03-07T12:21:48.766Z',
  v: 0,
  req: {
    id: 42,
    method: 'GET',
    url: '/',
    headers: {
      host: 'localhost:50201',
      connection: 'close'
    },
    remoteAddress: '::ffff:127.0.0.1',
    remotePort: 50202
  }
}
pinoHttp.stdSerializers.res

Generates a JSONifiable object from the HTTP response object passed to the createServer callback of Node's HTTP server.

It returns an object in the form:

{
  pid: 93581,
  hostname: 'myhost',
  level: 30,
  msg: 'my response',
  time: '2016-03-07T12:23:18.041Z',
  v: 0,
  res: {
    statusCode: 200,
    header: 'HTTP/1.1 200 OK\r\nDate: Mon, 07 Mar 2016 12:23:18 GMT\r\nConnection: close\r\nContent-Length: 5\r\n\r\n'
  }
}

Custom serializers

Each of the standard serializers can be extended by supplying a corresponding custom serializer. For example, let's assume the request object has custom properties attached to it, and that all of the custom properties are prefixed by foo. In order to show these properties, along with the standard serialized properties, in the resulting logs, we can supply a serializer like:

const logger = require('pino-http')({
  serializers: {
    req (req) {
      Object.keys(req.raw).forEach((k) => {
        if (k.startsWith('foo')) {
          req[k] = req.raw[k]
        }
      })
      return req
    }
  }
})

If you prefer to work with the raw value directly, or you want to honor the custom serializers already defined by opts.logger, you can pass in opts.wrapSerializers as false:

const logger = require('pino-http')({
  wrapSerializers: false,
  serializers: {
    req (req) {
      // `req` is the raw `IncomingMessage` object, not the already serialized request from `pino.stdSerializers.req`.
      return {
        message: req.foo
      };
    }
  }
})
Logging request body

Logging of requests' bodies is disabled by default since it can cause security risks such as having private user information (password, other GDPR-protected data, etc.) logged (and persisted in most setups). However if enabled, sensitive information can be redacted as per redaction documentation.

Furthermore, logging more bytes does slow down throughput. This video by pino maintainers Matteo Collina & David Mark Clements goes into this in more detail.

After considering these factors, logging of the request body can be achieved as follows:

const http = require('http')
const logger = require('pino-http')({
  serializers: {
    req(req) {
      req.body = req.raw.body;
      return req;
    },
  },
});
Custom serializers + custom log attribute keys

If custom attribute keys for req, res, or err log keys have been provided, serializers will be applied with the following order of precedence:

serializer matching custom key > serializer matching default key > default pino serializer

Team

Matteo Collina

https://github.com/mcollina

https://www.npmjs.com/~matteo.collina

https://twitter.com/matteocollina

David Mark Clements

https://github.com/davidmarkclements

https://www.npmjs.com/~davidmarkclements

https://twitter.com/davidmarkclem

Acknowledgements

This project was kindly sponsored by nearForm.

Logo and identity designed by Beibhinn Murphy O'Brien: https://www.behance.net/BeibhinnMurphyOBrien.

License

MIT

More Repositories

1

pino

🌲 super fast, all natural json logger
JavaScript
14,160
star
2

pino-pretty

🌲Basic prettifier for Pino log lines
JavaScript
1,212
star
3

sonic-boom

Extremely fast utf8 only stream implementation
JavaScript
266
star
4

thread-stream

A streaming way to send data to a Node.js Worker Thread
JavaScript
229
star
5

express-pino-logger

🌲 an express middleware to log with pino
JavaScript
199
star
6

pino-elasticsearch

🌲 load pino logs into Elasticsearch
JavaScript
176
star
7

pino-debug

🌲high performance debug logging 🐞
JavaScript
147
star
8

koa-pino-logger

🌲 pino logging koa middleware
JavaScript
91
star
9

pino-tee

🌲 tee pino logs into a file, with multiple levels
JavaScript
89
star
10

pino-multi-stream

🌲 A wrapper for Pino to provide Bunyan's multiple stream API
JavaScript
69
star
11

pino-nextjs-example

JavaScript
66
star
12

pino-noir

🌲 pino log redaction 🍷
JavaScript
66
star
13

pino-std-serializers

🌲 A list of standard object serializers for the Pino logger
JavaScript
58
star
14

pino-caller

🌲 Include call site of pino log messages
JavaScript
56
star
15

pino-mongodb

🌲 Insert JSON from stdin into MongoDB
JavaScript
54
star
16

pino-socket

🌲 A transport for sending pino logs to network sockets
JavaScript
42
star
17

pino-abstract-transport

Write Pino transports easily
JavaScript
34
star
18

pino-syslog

🌲 A transport for reformatting pino logs into standard syslog format
JavaScript
29
star
19

pino-arborsculpture

🌲 Change Pino log levels in a running process
JavaScript
24
star
20

pino-opentelemetry-transport

OpenTelemetry transport for Pino
JavaScript
21
star
21

pino-webpack-plugin

JavaScript
19
star
22

quick-format-unescaped

Solves a problem with util.format
JavaScript
17
star
23

pino-gelf

🌲 Convert Pino logs to GELF format and send to Graylog
JavaScript
13
star
24

restify-pino-logger

🌲 pino logging restify middleware
JavaScript
12
star
25

pino-inspector

Send your pino logs to the node inspector!
JavaScript
12
star
26

pino-http-print

🌲 debug HTTP printer for pino
JavaScript
9
star
27

pino-filter

🌲 A transport to filter log lines in the manner of the `debug` module
JavaScript
9
star
28

real-require

Keep require and import consistent after bundling or transpiling.
JavaScript
8
star
29

pino-clf

🌲 Transport which transforms Pino HTTP logs into Common Log Format
JavaScript
5
star
30

getpino.io

The website for pino
CSS
5
star
31

pino-toke

🌲 Transform Pino HTTP log messages with a format string
JavaScript
5
star
32

pino-test

JavaScript
2
star
33

pino-sapling

🌲 seed template for creating pino plugins/libraries/transports/utilities/modules
JavaScript
2
star
34

community

🌲 data on the members of the pino community
JavaScript
1
star
35

rill-pino-logger

🌲pino logging rill middleware
JavaScript
1
star