pino-debug [![stability][0]][1]

[![npm version][2]][3] [![build status][4]][5] [![test coverage][6]][7]
[![downloads][8]][9] [![dependencies freshness][14]][15] [![js-standard-style][10]][11]

High performance debug logging.

Seamlessly integrates the [debug][12] module with the high performance [pino][13]
logger so you can turn on debug logs in production scenarios
with minimum overhead.

* Up to 10x faster than using [debug][12] (20x in extreme mode!)
* JSON output with more detail (pino/bunyan/bole format)
* Safe with circular references ([debug][12] isn't)
* No need to replace any debug logging calls
* Associate namespaces with log levels
* Compatible with the entire pino ecosystem

Installation

sh
$ npm install --save pino-debug


Usage
$3
If all you want is fast JSON logging to STDOUT

`sh $ DEBUG=* node -r pino-debug app.js`

Namespaces are enabled the usual way, via the DEBUGenvironment variable.

The namespace is also included in the log output, in the ns key.

Here's a sample log when the above is applied to a generic express app:

`json {"pid":8784,"hostname":"Davids-MacBook-Pro.local","level":20,"time":1480277659273,"msg":"skip empty body","ns":"body-parser:json","v":1}`

`$3`

For fine grained control over output stream, and mappings between [debug][12] namespaces and [pino][13] logger levels, supply a [pino][13] instance and an optional options object with amap property containing mappings.

NOTE: pino-debugmust be required at the entry point of your node process, before any other modules have been loaded

Again this example assumes a generic express app:

`js const pinoDebug = require('pino-debug') const logger = require('pino')({level: process.env.LEVEL || 'info'}, process.stderr); pinoDebug(logger, { auto: true, // default map: { 'example:server': 'info', 'express:router': 'debug', '*': 'trace' // everything else - trace } })`

The auto option turns on any namespaces listed in the mapobject (so we don't have to use theDEBUG environment variable to turn them on).

`API`

NOTE: pino-debug can only be called once.

`$3`

Call pino-debug with a [pino][13] logger instance only and any debug namespaces enabled viaDEBUG or debug.enable will be logged with the level 20 ('debug').

Remember, if you want to see the messages you need to set the [pino][13] logger instance logging level to'debug'.

`$3`

Call pino-debug without arguments and a default [pino][13] instance will be created with the logging level set to 20 ('debug' level).

Any debug namespaces enabled via DEBUG or debug.enablewill be logged with the level 20 ('debug').

`$3`

This is the recommended usage. Call pino-debug with a [pino][13] logger instance, and anopts object containining map property.

#### opts.map {'debug-namespace: 'pino-loglevel-label'}

The keys of the mapproperty correspond to the same namespaces that can be set on theDEBUG environment variable:

`js pinoDebug(pinoInstance, { map: { 'my-app': 'info', 'some-dep:*': 'debug', '*': 'trace' } })`

#### opts.auto [true] | false

If true (default) any debug namespaces found in the keys of opts.mapwill be enabled.

Additionally, any debug namespaces enabled via DEBUG or debug.enablewill be logged with the level 20 ('debug').

If false, any namespaces that appear in opts.mapand are enabled viaDEBUG or debug.enablewill be logged to with the corresponding log level, (as specified in theopts.map). Any not specified in opts.map, but which are enabled viaDEBUG or debug.enable will be logged with the level 20 ('debug').

#### opts.skip Array

Equivalent of prefixing a namespace with dash (-) when specifyingDEBUG namespaces. Any namespaces specified will not be logged.

`Benchmarks`

`sh $ npm run bench`

`sh ========== basic averages Pino average: 249 Debug average: 395 PinoDebug average: 244 PinoExtremeDebug average: 119 ========== ========== object averages PinoObj average: 262 DebugObj average: 2448 PinoDebugObj average: 256 PinoExtremeDebugDeepObj average: 126 ========== ========== deepobject averages PinoDeepObj average: 4809 DebugDeepObj average: 30083 PinoDebugDeepObj average: 4793 PinoExtremeDebugDeepObj average: 4810 ==========`

`Example Folder`

The example folder has a generic express app, with some additions.

The package.json file has the following scripts:

`"start": "node ./bin/www", "start-preload": "DEBUG=* node -r ../ ./bin/www", "start-programmatic": "./bin/www-programmatic", "start-programmatic-debug": "LEVEL=debug ./bin/www-programmatic", "start-programmatic-trace": "LEVEL=trace ./bin/www-programmatic"`

The start-preloadscript demonstrates preload usage. It set's theDEBUGenvironment variable to log everything, and then uses the-r flag to load pino-debug (relatively referenced).

The three scripts beginning start-programmaticall use a different entry point wherepino-debughas been required and instantiated with a [pino`][13] instance and the mappings (as shown in usage examples).

License

MIT

Acknowledgements

pino-debug [![stability][0]][1]

[![npm version][2]][3] [![build status][4]][5] [![test coverage][6]][7]
[![downloads][8]][9] [![dependencies freshness][14]][15] [![js-standard-style][10]][11]

High performance debug logging.

Seamlessly integrates the [debug][12] module with the high performance [pino][13]
logger so you can turn on debug logs in production scenarios
with minimum overhead.

Installation

sh
$ npm install --save pino-debug


Usage
$3
If all you want is fast JSON logging to STDOUT

`sh $ DEBUG=* node -r pino-debug app.js`

Namespaces are enabled the usual way, via the DEBUGenvironment variable.

The namespace is also included in the log output, in the ns key.

Here's a sample log when the above is applied to a generic express app:

`json {"pid":8784,"hostname":"Davids-MacBook-Pro.local","level":20,"time":1480277659273,"msg":"skip empty body","ns":"body-parser:json","v":1}`

`$3`

NOTE: pino-debugmust be required at the entry point of your node process, before any other modules have been loaded

Again this example assumes a generic express app:

The auto option turns on any namespaces listed in the mapobject (so we don't have to use theDEBUG environment variable to turn them on).

`API`

NOTE: pino-debug can only be called once.

`$3`

Call pino-debug with a [pino][13] logger instance only and any debug namespaces enabled viaDEBUG or debug.enable will be logged with the level 20 ('debug').

Remember, if you want to see the messages you need to set the [pino][13] logger instance logging level to'debug'.

`$3`

Call pino-debug without arguments and a default [pino][13] instance will be created with the logging level set to 20 ('debug' level).

Any debug namespaces enabled via DEBUG or debug.enablewill be logged with the level 20 ('debug').

`$3`

This is the recommended usage. Call pino-debug with a [pino][13] logger instance, and anopts object containining map property.

#### opts.map {'debug-namespace: 'pino-loglevel-label'}

The keys of the mapproperty correspond to the same namespaces that can be set on theDEBUG environment variable:

`js pinoDebug(pinoInstance, { map: { 'my-app': 'info', 'some-dep:*': 'debug', '*': 'trace' } })`

#### opts.auto [true] | false

If true (default) any debug namespaces found in the keys of opts.mapwill be enabled.

Additionally, any debug namespaces enabled via DEBUG or debug.enablewill be logged with the level 20 ('debug').

#### opts.skip Array

Equivalent of prefixing a namespace with dash (-) when specifyingDEBUG namespaces. Any namespaces specified will not be logged.

`Benchmarks`

`sh $ npm run bench`

`Example Folder`

The example folder has a generic express app, with some additions.

The package.json file has the following scripts:

The start-preloadscript demonstrates preload usage. It set's theDEBUGenvironment variable to log everything, and then uses the-r flag to load pino-debug (relatively referenced).

License

MIT