1 | # API
|
2 |
|
3 | * [pino() => logger](#export)
|
4 | * [options](#options)
|
5 | * [destination](#destination)
|
6 | * [destination\[Symbol.for('pino.metadata')\]](#metadata)
|
7 | * [Logger Instance](#logger)
|
8 | * [logger.trace()](#trace)
|
9 | * [logger.debug()](#debug)
|
10 | * [logger.info()](#info)
|
11 | * [logger.warn()](#warn)
|
12 | * [logger.error()](#error)
|
13 | * [logger.fatal()](#fatal)
|
14 | * [logger.child()](#child)
|
15 | * [logger.bindings()](#bindings)
|
16 | * [logger.flush()](#flush)
|
17 | * [logger.level](#level)
|
18 | * [logger.isLevelEnabled()](#islevelenabled)
|
19 | * [logger.levels](#levels)
|
20 | * [logger\[Symbol.for('pino.serializers')\]](#serializers)
|
21 | * [Event: 'level-change'](#level-change)
|
22 | * [logger.version](#version)
|
23 | * [Statics](#statics)
|
24 | * [pino.destination()](#pino-destination)
|
25 | * [pino.final()](#pino-final)
|
26 | * [pino.stdSerializers](#pino-stdserializers)
|
27 | * [pino.stdTimeFunctions](#pino-stdtimefunctions)
|
28 | * [pino.symbols](#pino-symbols)
|
29 | * [pino.version](#pino-version)
|
30 |
|
31 | <a id="export"></a>
|
32 | ## `pino([options], [destination]) => logger`
|
33 |
|
34 | The exported `pino` function takes two optional arguments,
|
35 | [`options`](#options) and [`destination`](#destination) and
|
36 | returns a [logger instance](#logger).
|
37 |
|
38 | <a id=options></a>
|
39 | ### `options` (Object)
|
40 |
|
41 | #### `name` (String)
|
42 |
|
43 | Default: `undefined`
|
44 |
|
45 | The name of the logger. When set adds a `name` field to every JSON line logged.
|
46 |
|
47 | #### `level` (String)
|
48 |
|
49 | Default: `'info'`
|
50 |
|
51 | One of `'fatal'`, `'error'`, `'warn'`, `'info`', `'debug'`, `'trace'` or `'silent'`.
|
52 |
|
53 | Additional levels can be added to the instance via the `customLevels` option.
|
54 |
|
55 | * See [`customLevels` option](#opt-customlevels)
|
56 |
|
57 | <a id=opt-customlevels></a>
|
58 | #### `customLevels` (Object)
|
59 |
|
60 | Default: `undefined`
|
61 |
|
62 | Use this option to define additional logging levels.
|
63 | The keys of the object correspond the namespace of the log level,
|
64 | and the values should be the numerical value of the level.
|
65 |
|
66 | ```js
|
67 | const logger = pino({
|
68 | customLevels: {
|
69 | foo: 35
|
70 | }
|
71 | })
|
72 | logger.foo('hi')
|
73 | ```
|
74 |
|
75 | <a id=opt-useOnlyCustomLevels></a>
|
76 | #### `useOnlyCustomLevels` (Boolean)
|
77 |
|
78 | Default: `false`
|
79 |
|
80 | Use this option to only use defined `customLevels` and omit Pino's levels.
|
81 | Logger's default `level` must be changed to a value in `customLevels` in order to use `useOnlyCustomLevels`
|
82 | Warning: this option may not be supported by downstream transports.
|
83 |
|
84 | ```js
|
85 | const logger = pino({
|
86 | customLevels: {
|
87 | foo: 35
|
88 | },
|
89 | useOnlyCustomLevels: true,
|
90 | level: 'foo'
|
91 | })
|
92 | logger.foo('hi')
|
93 | logger.info('hello') // Will throw an error saying info in not found in logger object
|
94 | ```
|
95 |
|
96 | #### `mixin` (Function):
|
97 |
|
98 | Default: `undefined`
|
99 |
|
100 | If provided, the `mixin` function is called each time one of the active
|
101 | logging methods is called. The function must synchronously return an
|
102 | object. The properties of the returned object will be added to the
|
103 | logged JSON.
|
104 |
|
105 | ```js
|
106 | let n = 0
|
107 | const logger = pino({
|
108 | mixin () {
|
109 | return { line: ++n }
|
110 | }
|
111 | })
|
112 | logger.info('hello')
|
113 | // {"level":30,"time":1573664685466,"pid":78742,"hostname":"x","line":1,"msg":"hello","v":1}
|
114 | logger.info('world')
|
115 | // {"level":30,"time":1573664685469,"pid":78742,"hostname":"x","line":2,"msg":"world","v":1}
|
116 | ```
|
117 |
|
118 | #### `redact` (Array | Object):
|
119 |
|
120 | Default: `undefined`
|
121 |
|
122 | As an array, the `redact` option specifies paths that should
|
123 | have their values redacted from any log output.
|
124 |
|
125 | Each path must be a string using a syntax which corresponds to JavaScript dot and bracket notation.
|
126 |
|
127 | If an object is supplied, three options can be specified:
|
128 | * `paths` (array): Required. An array of paths. See [redaction - Path Syntax ⇗](/docs/redaction.md#paths) for specifics.
|
129 | * `censor` (String|Function|Undefined): Optional. When supplied as a String the `censor` option will overwrite keys which are to be redacted. When set to `undefined` the the key will be removed entirely from the object.
|
130 | The `censor` option may also be a mapping function. The (synchronous) mapping function is called with the unredacted value. The value returned from the mapping function becomes the applied censor value. Default: `'[Redacted]'`
|
131 | value synchronously.
|
132 | Default: `'[Redacted]'`
|
133 | * `remove` (Boolean): Optional. Instead of censoring the value, remove both the key and the value. Default: `false`
|
134 |
|
135 | **WARNING**: Never allow user input to define redacted paths.
|
136 |
|
137 | * See the [redaction ⇗](/docs/redaction.md) documentation.
|
138 | * See [fast-redact#caveat ⇗](http://github.com/davidmarkclements/fast-redact#caveat)
|
139 |
|
140 | <a id=opt-hooks></a>
|
141 | #### `hooks` (Object)
|
142 |
|
143 | An object mapping to hook functions. Hook functions allow for customizing
|
144 | internal logger operations. Hook functions ***must*** be synchronous functions.
|
145 |
|
146 | ##### `logMethod`
|
147 |
|
148 | Allows for manipulating the parameters passed to logger methods. The signature
|
149 | for this hook is `logMethod (args, method) {}`, where `args` is an array
|
150 | of the arguments that were passed to the log method and `method` is the log
|
151 | method itself. This hook ***must*** invoke the `method` function by using
|
152 | apply, like so: `method.apply(this, newArgumentsArray)`.
|
153 |
|
154 | For example, Pino expects a binding object to be the first parameter with an
|
155 | optional string message as the second parameter. Using this hook the parameters
|
156 | can be flipped:
|
157 |
|
158 | ```js
|
159 | const hooks = {
|
160 | logMethod (inputArgs, method) {
|
161 | if (inputArgs.length >= 2) {
|
162 | const arg1 = inputArgs.shift()
|
163 | const arg2 = inputArgs.shift()
|
164 | return method.apply(this, [arg2, arg1, ...inputArgs])
|
165 | }
|
166 | return method.apply(this, inputArgs)
|
167 | }
|
168 | }
|
169 | ```
|
170 |
|
171 | <a id=opt-formatters></a>
|
172 | #### `formatters` (Object)
|
173 |
|
174 | An object containing functions for formatting the shape of the log lines.
|
175 | These functions should return a JSONifiable object and
|
176 | should never throw. These functions allow for full customization of
|
177 | the resulting log lines. For example, they can be used to change
|
178 | the level key name or to enrich the default metadata.
|
179 |
|
180 | ##### `level`
|
181 |
|
182 | Changes the shape of the log level. The default shape is `{ level: number }`.
|
183 | The function takes two arguments, the label of the level (e.g. `'info'`)
|
184 | and the numeric value (e.g. `30`).
|
185 |
|
186 | ```js
|
187 | const formatters = {
|
188 | level (label, number) {
|
189 | return { level: number }
|
190 | }
|
191 | }
|
192 | ```
|
193 |
|
194 | ##### `bindings`
|
195 |
|
196 | Changes the shape of the bindings. The default shape is `{ pid, hostname }`.
|
197 | The function takes a single argument, the bindings object. It will
|
198 | be called every time a child logger is created.
|
199 |
|
200 | ```js
|
201 | const formatters = {
|
202 | bindings (bindings) {
|
203 | return { pid: bindings.pid, hostname: bindings.hostname }
|
204 | }
|
205 | }
|
206 | ```
|
207 |
|
208 | ##### `log`
|
209 |
|
210 | Changes the shape of the log object. This function will be called every time
|
211 | one of the log methods (such as `.info`) is called. All arguments passed to the
|
212 | log method, except the message, will be pass to this function. By default it does
|
213 | not change the shape of the log object.
|
214 |
|
215 | ```js
|
216 | const formatters = {
|
217 | log (object) {
|
218 | return object
|
219 | }
|
220 | }
|
221 | ```
|
222 |
|
223 | <a id=opt-serializers></a>
|
224 | #### `serializers` (Object)
|
225 |
|
226 | Default: `{err: pino.stdSerializers.err}`
|
227 |
|
228 | An object containing functions for custom serialization of objects.
|
229 | These functions should return an JSONifiable object and they
|
230 | should never throw. When logging an object, each top-level property
|
231 | matching the exact key of a serializer will be serialized using the defined serializer.
|
232 |
|
233 | * See [pino.stdSerializers](#pino-stdserializers)
|
234 |
|
235 | ##### `serializers[Symbol.for('pino.*')]` (Function) - DEPRECATED
|
236 |
|
237 | Use `formatters.log` instead.
|
238 |
|
239 | #### `base` (Object)
|
240 |
|
241 | Default: `{pid: process.pid, hostname: os.hostname}`
|
242 |
|
243 | Key-value object added as child logger to each log line.
|
244 |
|
245 | Set to `null` to avoid adding `pid`, `hostname` and `name` properties to each log.
|
246 |
|
247 | #### `enabled` (Boolean)
|
248 |
|
249 | Default: `true`
|
250 |
|
251 | Set to `false` to disable logging.
|
252 |
|
253 | #### `crlf` (Boolean)
|
254 |
|
255 | Default: `false`
|
256 |
|
257 | Set to `true` to logs newline delimited JSON with `\r\n` instead of `\n`.
|
258 |
|
259 | <a id=opt-timestamp></a>
|
260 | #### `timestamp` (Boolean | Function)
|
261 |
|
262 | Default: `true`
|
263 |
|
264 | Enables or disables the inclusion of a timestamp in the
|
265 | log message. If a function is supplied, it must synchronously return a JSON string
|
266 | representation of the time, e.g. `,"time":1493426328206` (which is the default).
|
267 |
|
268 | If set to `false`, no timestamp will be included in the output.
|
269 | See [stdTimeFunctions](#pino-stdtimefunctions) for a set of available functions
|
270 | for passing in as a value for this option.
|
271 |
|
272 | **Caution**: attempting to format time in-process will significantly impact logging performance.
|
273 |
|
274 | <a id=opt-messagekey></a>
|
275 | #### `messageKey` (String)
|
276 |
|
277 | Default: `'msg'`
|
278 |
|
279 | The string key for the 'message' in the JSON object.
|
280 |
|
281 | <a id=opt-nestedkey></a>
|
282 | #### `nestedKey` (String)
|
283 |
|
284 | Default: `null`
|
285 |
|
286 | If there's a chance that objects being logged have properties that conflict with those from pino itself (`level`, `timestamp`, `v`, `pid`, etc)
|
287 | and duplicate keys in your log records are undesirable, pino can be configured with a `nestedKey` option that causes any `object`s that are logged
|
288 | to be placed under a key whose name is the value of `nestedKey`.
|
289 |
|
290 | This way, when searching something like Kibana for values, one can consistently search under the configured `nestedKey` value instead of the root log record keys.
|
291 |
|
292 | For example,
|
293 | ```js
|
294 | const logger = require('pino')({
|
295 | nestedKey: 'payload'
|
296 | })
|
297 |
|
298 | const thing = { level: 'hi', time: 'never', foo: 'bar'} // has pino-conflicting properties!
|
299 | logger.info(thing)
|
300 |
|
301 | // logs the following:
|
302 | // {"level":30,"time":1578357790020,"pid":91736,"hostname":"x","payload":{"level":"hi","time":"never","foo":"bar"},"v":1}
|
303 | ```
|
304 | In this way, logged objects' properties don't conflict with pino's standard logging properties,
|
305 | and searching for logged objects can start from a consistent path.
|
306 |
|
307 | <a id=prettyPrint></a>
|
308 | #### `prettyPrint` (Boolean | Object)
|
309 |
|
310 | Default: `false`
|
311 |
|
312 | Enables pretty printing log logs. This is intended for non-production
|
313 | configurations. This may be set to a configuration object as outlined in the
|
314 | [`pino-pretty` documentation](https://github.com/pinojs/pino-pretty).
|
315 |
|
316 | The options object may additionally contain a `prettifier` property to define
|
317 | which prettifier module to use. When not present, `prettifier` defaults to
|
318 | `'pino-pretty'`. Regardless of the value, the specified prettifier module
|
319 | must be installed as a separate dependency:
|
320 |
|
321 | ```sh
|
322 | npm install pino-pretty
|
323 | ```
|
324 |
|
325 | <a id="useLevelLabels"></a>
|
326 | #### `useLevelLabels` (Boolean) - DEPRECATED
|
327 |
|
328 | Use `formatters.level` instead. This will be removed in v7.
|
329 |
|
330 | <a id="changeLevelName"></a>
|
331 | #### `changeLevelName` (String) - DEPRECATED
|
332 | Use `formatters.level` instead. This will be removed in v7.
|
333 |
|
334 | <a id="levelKey"></a>
|
335 | #### `levelKey` (String) - DEPRECATED
|
336 |
|
337 | Use `formatters.level` instead. This will be removed in v7.
|
338 |
|
339 | #### `browser` (Object)
|
340 |
|
341 | Browser only, may have `asObject` and `write` keys. This option is separately
|
342 | documented in the [Browser API ⇗](/docs/browser.md) documentation.
|
343 |
|
344 | * See [Browser API ⇗](/docs/browser.md)
|
345 |
|
346 | <a id="destination"></a>
|
347 | ### `destination` (SonicBoom | WritableStream | String)
|
348 |
|
349 | Default: `pino.destination(1)` (STDOUT)
|
350 |
|
351 | The `destination` parameter, at a minimum must be an object with a `write` method.
|
352 | An ordinary Node.js `stream` can be passed as the destination (such as the result
|
353 | of `fs.createWriteStream`) but for peak log writing performance it is strongly
|
354 | recommended to use `pino.destination` to create the destination stream.
|
355 |
|
356 | ```js
|
357 | // pino.destination(1) by default
|
358 | const stdoutLogger = require('pino')()
|
359 |
|
360 | // destination param may be in first position when no options:
|
361 | const fileLogger = require('pino')( pino.destination('/log/path'))
|
362 |
|
363 | // use the stderr file handle to log to stderr:
|
364 | const opts = {name: 'my-logger'}
|
365 | const stderrLogger = require('pino')(opts, pino.destination(2))
|
366 |
|
367 | // automatic wrapping in pino.destination
|
368 | const fileLogger = require('pino')('/log/path')
|
369 | ```
|
370 |
|
371 | However, there are some special instances where `pino.destination` is not used as the default:
|
372 |
|
373 | + When something, e.g a process manager, has monkey-patched `process.stdout.write`.
|
374 |
|
375 | In these cases `process.stdout` is used instead.
|
376 |
|
377 | * See [`pino.destination`](#pino-destination)
|
378 |
|
379 | <a id="metadata"></a>
|
380 | #### `destination[Symbol.for('pino.metadata')]`
|
381 |
|
382 | Default: `false`
|
383 |
|
384 | Using the global symbol `Symbol.for('pino.metadata')` as a key on the `destination` parameter and
|
385 | setting the key it to `true`, indicates that the following properties should be
|
386 | set on the `destination` object after each log line is written:
|
387 |
|
388 | * the last logging level as `destination.lastLevel`
|
389 | * the last logging message as `destination.lastMsg`
|
390 | * the last logging object as `destination.lastObj`
|
391 | * the last time as `destination.lastTime`, which will be the partial string returned
|
392 | by the time function.
|
393 | * the last logger instance as `destination.lastLogger` (to support child
|
394 | loggers)
|
395 |
|
396 | For a full reference for using `Symbol.for('pino.metadata')`, see the [`pino-multi-stream` ⇗](https://github.com/pinojs/pino-multi-stream)
|
397 | module.
|
398 |
|
399 | The following is a succinct usage example:
|
400 |
|
401 | ```js
|
402 | const dest = pino.destination('/dev/null')
|
403 | dest[Symbol.for('pino.metadata')] = true
|
404 | const logger = pino(dest)
|
405 | logger.info({a: 1}, 'hi')
|
406 | const { lastMsg, lastLevel, lastObj, lastTime} = dest
|
407 | console.log(
|
408 | 'Logged message "%s" at level %d with object %o at time %s',
|
409 | lastMsg, lastLevel, lastObj, lastTime
|
410 | ) // Logged message "hi" at level 30 with object { a: 1 } at time 1531590545089
|
411 | ```
|
412 |
|
413 | * See [`pino-multi-stream` ⇗](https://github.com/pinojs/pino-multi-stream)
|
414 |
|
415 | <a id="logger"></a>
|
416 | ## Logger Instance
|
417 |
|
418 | The logger instance is the object returned by the main exported
|
419 | [`pino`](#export) function.
|
420 |
|
421 | The primary purpose of the logger instance is to provide logging methods.
|
422 |
|
423 | The default logging methods are `trace`, `debug`, `info`, `warn`, `error`, and `fatal`.
|
424 |
|
425 | Each logging method has the following signature:
|
426 | `([mergingObject], [message], [...interpolationValues])`.
|
427 |
|
428 | The parameters are explained below using the `logger.info` method but the same applies to all logging methods.
|
429 |
|
430 | ### Logging Method Parameters
|
431 |
|
432 | <a id=mergingobject></a>
|
433 | #### `mergingObject` (Object)
|
434 |
|
435 | An object can optionally be supplied as the first parameter. Each enumerable key and value
|
436 | of the `mergingObject` is copied in to the JSON log line.
|
437 |
|
438 | ```js
|
439 | logger.info({MIX: {IN: true}})
|
440 | // {"level":30,"time":1531254555820,"pid":55956,"hostname":"x","MIX":{"IN":true}}
|
441 | ```
|
442 |
|
443 | <a id=message></a>
|
444 | #### `message` (String)
|
445 |
|
446 | A `message` string can optionally be supplied as the first parameter, or
|
447 | as the second parameter after supplying a `mergingObject`.
|
448 |
|
449 | By default, the contents of the `message` parameter will be merged into the
|
450 | JSON log line under the `msg` key:
|
451 |
|
452 | ```js
|
453 | logger.info('hello world')
|
454 | // {"level":30,"time":1531257112193,"msg":"hello world","pid":55956,"hostname":"x"}
|
455 | ```
|
456 |
|
457 | The `message` parameter takes precedence over the `mergedObject`.
|
458 | That is, if a `mergedObject` contains a `msg` property, and a `message` parameter
|
459 | is supplied in addition, the `msg` property in the output log will be the value of
|
460 | the `message` parameter not the value of the `msg` property on the `mergedObject`.
|
461 |
|
462 | The `messageKey` option can be used at instantiation time to change the namespace
|
463 | from `msg` to another string as preferred.
|
464 |
|
465 | The `message` string may contain a printf style string with support for
|
466 | the following placeholders:
|
467 |
|
468 | * `%s` – string placeholder
|
469 | * `%d` – digit placeholder
|
470 | * `%O`, `%o` and `%j` – object placeholder
|
471 |
|
472 | Values supplied as additional arguments to the logger method will
|
473 | then be interpolated accordingly.
|
474 |
|
475 | * See [`messageKey` pino option](#opt-messagekey)
|
476 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
477 |
|
478 | <a id=interpolationvalues></a>
|
479 | #### `...interpolationValues` (Any)
|
480 |
|
481 | All arguments supplied after `message` are serialized and interpolated according
|
482 | to any supplied printf-style placeholders (`%s`, `%d`, `%o`|`%O`|`%j`) to form
|
483 | the final output `msg` value for the JSON log line.
|
484 |
|
485 | ```js
|
486 | logger.info('hello', 'world')
|
487 | // {"level":30,"time":1531257618044,"msg":"hello world","pid":55956,"hostname":"x"}
|
488 | ```
|
489 |
|
490 | ```js
|
491 | logger.info('hello', {worldly: 1})
|
492 | // {"level":30,"time":1531257797727,"msg":"hello {\"worldly\":1}","pid":55956,"hostname":"x"}
|
493 | ```
|
494 |
|
495 | ```js
|
496 | logger.info('%o hello', {worldly: 1})
|
497 | // {"level":30,"time":1531257826880,"msg":"{\"worldly\":1} hello","pid":55956,"hostname":"x"}
|
498 | ```
|
499 |
|
500 | * See [`message` log method parameter](#message)
|
501 |
|
502 | <a id="trace"></a>
|
503 | ### `logger.trace([mergingObject], [message], [...interpolationValues])`
|
504 |
|
505 | Write a `'trace'` level log, if the configured [`level`](#level) allows for it.
|
506 |
|
507 | * See [`mergingObject` log method parameter](#mergingobject)
|
508 | * See [`message` log method parameter](#message)
|
509 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
510 |
|
511 | <a id="debug"></a>
|
512 | ### `logger.debug([mergingObject], [message], [...interpolationValues])`
|
513 |
|
514 | Write a `'debug'` level log, if the configured `level` allows for it.
|
515 |
|
516 | * See [`mergingObject` log method parameter](#mergingobject)
|
517 | * See [`message` log method parameter](#message)
|
518 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
519 |
|
520 | <a id="info"></a>
|
521 | ### `logger.info([mergingObject], [message], [...interpolationValues])`
|
522 |
|
523 | Write an `'info'` level log, if the configured `level` allows for it.
|
524 |
|
525 | * See [`mergingObject` log method parameter](#mergingobject)
|
526 | * See [`message` log method parameter](#message)
|
527 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
528 |
|
529 | <a id="warn"></a>
|
530 | ### `logger.warn([mergingObject], [message], [...interpolationValues])`
|
531 |
|
532 | Write a `'warn'` level log, if the configured `level` allows for it.
|
533 |
|
534 | * See [`mergingObject` log method parameter](#mergingobject)
|
535 | * See [`message` log method parameter](#message)
|
536 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
537 |
|
538 | <a id="error"></a>
|
539 | ### `logger.error([mergingObject], [message], [...interpolationValues])`
|
540 |
|
541 | Write a `'error'` level log, if the configured `level` allows for it.
|
542 |
|
543 | * See [`mergingObject` log method parameter](#mergingobject)
|
544 | * See [`message` log method parameter](#message)
|
545 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
546 |
|
547 | <a id="fatal"></a>
|
548 | ### `logger.fatal([mergingObject], [message], [...interpolationValues])`
|
549 |
|
550 | Write a `'fatal'` level log, if the configured `level` allows for it.
|
551 |
|
552 | Since `'fatal'` level messages are intended to be logged just prior to the process exiting the `fatal`
|
553 | method will always sync flush the destination.
|
554 | Therefore it's important not to misuse `fatal` since
|
555 | it will cause performance overhead if used for any
|
556 | other purpose than writing final log messages before
|
557 | the process crashes or exits.
|
558 |
|
559 | * See [`mergingObject` log method parameter](#mergingobject)
|
560 | * See [`message` log method parameter](#message)
|
561 | * See [`...interpolationValues` log method parameter](#interpolationvalues)
|
562 |
|
563 |
|
564 | <a id="child"></a>
|
565 | ### `logger.child(bindings) => logger`
|
566 |
|
567 | The `logger.child` method allows for the creation of stateful loggers,
|
568 | where key-value pairs can be pinned to a logger causing them to be output
|
569 | on every log line.
|
570 |
|
571 | Child loggers use the same output stream as the parent and inherit
|
572 | the current log level of the parent at the time they are spawned.
|
573 |
|
574 | The log level of a child is mutable. It can be set independently
|
575 | of the parent either by setting the [`level`](#level) accessor after creating
|
576 | the child logger or using the reserved [`bindings.level`](#bindingslevel-string) key.
|
577 |
|
578 | #### `bindings` (Object)
|
579 |
|
580 | An object of key-value pairs to include in every log line output
|
581 | via the returned child logger.
|
582 |
|
583 | ```js
|
584 | const child = logger.child({ MIX: {IN: 'always'} })
|
585 | child.info('hello')
|
586 | // {"level":30,"time":1531258616689,"msg":"hello","pid":64849,"hostname":"x","MIX":{"IN":"always"}}
|
587 | child.info('child!')
|
588 | // {"level":30,"time":1531258617401,"msg":"child!","pid":64849,"hostname":"x","MIX":{"IN":"always"}}
|
589 | ```
|
590 |
|
591 | The `bindings` object may contain any key except for reserved configuration keys `level` and `serializers`.
|
592 |
|
593 | ##### `bindings.level` (String)
|
594 |
|
595 | If a `level` property is present in the `bindings` object passed to `logger.child`
|
596 | it will override the child logger level.
|
597 |
|
598 | ```js
|
599 | const logger = pino()
|
600 | logger.debug('nope') // will not log, since default level is info
|
601 | const child = logger.child({foo: 'bar', level: 'debug'})
|
602 | child.debug('debug!') // will log as the `level` property set the level to debug
|
603 | ```
|
604 |
|
605 | ##### `bindings.serializers` (Object)
|
606 |
|
607 | Child loggers inherit the [serializers](#opt-serializers) from the parent logger.
|
608 |
|
609 | Setting the `serializers` key of the `bindings` object will override
|
610 | any configured parent serializers.
|
611 |
|
612 | ```js
|
613 | const logger = require('pino')()
|
614 | logger.info({test: 'will appear'})
|
615 | // {"level":30,"time":1531259759482,"pid":67930,"hostname":"x","test":"will appear"}
|
616 | const child = logger.child({serializers: {test: () => `child-only serializer`}})
|
617 | child.info({test: 'will be overwritten'})
|
618 | // {"level":30,"time":1531259784008,"pid":67930,"hostname":"x","test":"child-only serializer"}
|
619 | ```
|
620 |
|
621 | * See [`serializers` option](#opt-serializers)
|
622 | * See [pino.stdSerializers](#pino-stdSerializers)
|
623 |
|
624 | <a id="bindings"></a>
|
625 | ### `logger.bindings()`
|
626 |
|
627 | Returns an object containing all the current bindings, cloned from the ones passed in via `logger.child()`.
|
628 | ```js
|
629 | const child = logger.child({ foo: 'bar' })
|
630 | console.log(child.bindings())
|
631 | // { foo: 'bar' }
|
632 | const anotherChild = child.child({ MIX: { IN: 'always' } })
|
633 | console.log(anotherChild.bindings())
|
634 | // { foo: 'bar', MIX: { IN: 'always' } }
|
635 | ```
|
636 |
|
637 | <a id="flush"></a>
|
638 | ### `logger.flush()`
|
639 |
|
640 | Flushes the content of the buffer when using `pino.destination({
|
641 | sync: false })`.
|
642 |
|
643 | This is an asynchronous, fire and forget, operation.
|
644 |
|
645 | The use case is primarily for asynchronous logging, which may buffer
|
646 | log lines while others are being written. The `logger.flush` method can be
|
647 | used to flush the logs
|
648 | on an long interval, say ten seconds. Such a strategy can provide an
|
649 | optimium balance between extremely efficient logging at high demand periods
|
650 | and safer logging at low demand periods.
|
651 |
|
652 | * See [`destination` parameter](#destination)
|
653 | * See [Asynchronous Logging ⇗](/docs/asynchronous.md)
|
654 |
|
655 | <a id="level"></a>
|
656 | ### `logger.level` (String) [Getter/Setter]
|
657 |
|
658 | Set this property to the desired logging level.
|
659 |
|
660 | The core levels and their values are as follows:
|
661 |
|
662 | | | | | | | | | |
|
663 | |:-----------|-------|-------|------|------|-------|-------|---------:|
|
664 | | **Level:** | trace | debug | info | warn | error | fatal | silent |
|
665 | | **Value:** | 10 | 20 | 30 | 40 | 50 | 60 | Infinity |
|
666 |
|
667 | The logging level is a *minimum* level based on the associated value of that level.
|
668 |
|
669 | For instance if `logger.level` is `info` *(30)* then `info` *(30)*, `warn` *(40)*, `error` *(50)* and `fatal` *(60)* log methods will be enabled but the `trace` *(10)* and `debug` *(20)* methods, being less than 30, will not.
|
670 |
|
671 | The `silent` logging level is a specialized level which will disable all logging,
|
672 | there is no `silent` log method.
|
673 |
|
674 | <a id="islevelenabled"></a>
|
675 | ### `logger.isLevelEnabled(level)`
|
676 |
|
677 | A utility method for determining if a given log level will write to the destination.
|
678 |
|
679 | #### `level` (String)
|
680 |
|
681 | The given level to check against:
|
682 |
|
683 | ```js
|
684 | if (logger.isLevelEnabled('debug')) logger.debug('conditional log')
|
685 | ```
|
686 |
|
687 | #### `levelLabel` (String)
|
688 |
|
689 | Defines the method name of the new level.
|
690 |
|
691 | * See [`logger.level`](#level)
|
692 |
|
693 | #### `levelValue` (Number)
|
694 |
|
695 | Defines the associated minimum threshold value for the level, and
|
696 | therefore where it sits in order of priority among other levels.
|
697 |
|
698 | * See [`logger.level`](#level)
|
699 |
|
700 | <a id="levelVal"></a>
|
701 | ### `logger.levelVal` (Number)
|
702 |
|
703 | Supplies the integer value for the current logging level.
|
704 |
|
705 | ```js
|
706 | if (logger.levelVal === 30) {
|
707 | console.log('logger level is `info`')
|
708 | }
|
709 | ```
|
710 |
|
711 | <a id="levels"></a>
|
712 | ### `logger.levels` (Object)
|
713 |
|
714 | Levels are mapped to values to determine the minimum threshold that a
|
715 | logging method should be enabled at (see [`logger.level`](#level)).
|
716 |
|
717 | The `logger.levels` property holds the mappings between levels and values,
|
718 | and vice versa.
|
719 |
|
720 | ```sh
|
721 | $ node -p "require('pino')().levels"
|
722 | ```
|
723 |
|
724 | ```js
|
725 | { labels:
|
726 | { '10': 'trace',
|
727 | '20': 'debug',
|
728 | '30': 'info',
|
729 | '40': 'warn',
|
730 | '50': 'error',
|
731 | '60': 'fatal' },
|
732 | values:
|
733 | { fatal: 60, error: 50, warn: 40, info: 30, debug: 20, trace: 10 } }
|
734 | ```
|
735 |
|
736 | * See [`logger.level`](#level)
|
737 |
|
738 | <a id="serializers"></a>
|
739 | ### logger\[Symbol.for('pino.serializers')\]
|
740 |
|
741 | Returns the serializers as applied to the current logger instance. If a child logger did not
|
742 | register it's own serializer upon instantiation the serializers of the parent will be returned.
|
743 |
|
744 | <a id="level-change"></a>
|
745 | ### Event: 'level-change'
|
746 |
|
747 | The logger instance is also an [`EventEmitter ⇗`](https://nodejs.org/dist/latest/docs/api/events.html#events_class_eventemitter)
|
748 |
|
749 | A listener function can be attached to a logger via the `level-change` event
|
750 |
|
751 | The listener is passed four arguments:
|
752 |
|
753 | * `levelLabel` – the new level string, e.g `trace`
|
754 | * `levelValue` – the new level number, e.g `10`
|
755 | * `previousLevelLabel` – the prior level string, e.g `info`
|
756 | * `previousLevelValue` – the prior level numbebr, e.g `30`
|
757 |
|
758 | ```js
|
759 | const logger = require('pino')()
|
760 | logger.on('level-change', (lvl, val, prevLvl, prevVal) => {
|
761 | console.log('%s (%d) was changed to %s (%d)', lvl, val, prevLvl, prevVal)
|
762 | })
|
763 | logger.level = 'trace' // trigger event
|
764 | ```
|
765 |
|
766 | <a id="version"></a>
|
767 | ### `logger.version` (String)
|
768 |
|
769 | Exposes the Pino package version. Also available on the exported `pino` function.
|
770 |
|
771 | * See [`pino.version`](#pino-version)
|
772 |
|
773 | ## Statics
|
774 |
|
775 | <a id="pino-destination"></a>
|
776 | ### `pino.destination([opts]) => SonicBoom`
|
777 |
|
778 | Create a Pino Destination instance: a stream-like object with
|
779 | significantly more throughput (over 30%) than a standard Node.js stream.
|
780 |
|
781 | ```js
|
782 | const pino = require('pino')
|
783 | const logger = pino(pino.destination('./my-file'))
|
784 | const logger2 = pino(pino.destination())
|
785 | const logger3 = pino(pino.destination({
|
786 | dest: './my-file',
|
787 | minLength: 4096, // Buffer before writing
|
788 | sync: false // Asynchronous logging
|
789 | }))
|
790 | ```
|
791 |
|
792 | The `pino.destination` method may be passed a file path or a numerical file descriptor.
|
793 | By default, `pino.destination` will use `process.stdout.fd` (1) as the file descriptor.
|
794 |
|
795 | `pino.destination` is implemented on [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom).
|
796 |
|
797 | A `pino.destination` instance can also be used to reopen closed files
|
798 | (for example, for some log rotation scenarios), see [Reopening log files](/docs/help.md#reopening).
|
799 |
|
800 | * See [`destination` parameter](#destination)
|
801 | * See [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom)
|
802 | * See [Reopening log files](/docs/help.md#reopening)
|
803 | * See [Asynchronous Logging ⇗](/docs/asynchronous.md)
|
804 |
|
805 | <a id="pino-final"></a>
|
806 |
|
807 | ### `pino.final(logger, [handler]) => Function | FinalLogger`
|
808 |
|
809 | The `pino.final` method can be used to acquire a final logger instance
|
810 | or create an exit listener function.
|
811 |
|
812 | The `finalLogger` is a specialist logger that synchronously flushes
|
813 | on every write. This is important to guarantee final log writes,
|
814 | both when using `pino.extreme` target.
|
815 |
|
816 | Since final log writes cannot be guaranteed with normal Node.js streams,
|
817 | if the `destination` parameter of the `logger` supplied to `pino.final`
|
818 | is a Node.js stream `pino.final` will throw.
|
819 |
|
820 | The use of `pino.final` with `pino.destination` is not needed, as
|
821 | `pino.destination` writes things synchronously.
|
822 |
|
823 | #### `pino.final(logger, handler) => Function`
|
824 |
|
825 | In this case the `pino.final` method supplies an exit listener function that can be
|
826 | supplied to process exit events such as `exit`, `uncaughtException`,
|
827 | `SIGHUP` and so on.
|
828 |
|
829 | The exit listener function will call the supplied `handler` function
|
830 | with an error object (or else `null`), a `finalLogger` instance followed
|
831 | by any additional arguments the `handler` may be called with.
|
832 |
|
833 | ```js
|
834 | process.on('uncaughtException', pino.final(logger, (err, finalLogger) => {
|
835 | finalLogger.error(err, 'uncaughtException')
|
836 | process.exit(1)
|
837 | }))
|
838 | ```
|
839 |
|
840 | #### `pino.final(logger) => FinalLogger`
|
841 |
|
842 | In this case the `pino.final` method returns a finalLogger instance.
|
843 |
|
844 | ```js
|
845 | var finalLogger = pino.final(logger)
|
846 | finalLogger.info('exiting...')
|
847 | ```
|
848 |
|
849 | * See [`destination` parameter](#destination)
|
850 | * See [Exit logging help](/docs/help.md#exit-logging)
|
851 | * See [Extreme mode ⇗](/docs/extreme.md)
|
852 | * See [Log loss prevention ⇗](/docs/extreme.md#log-loss-prevention)
|
853 |
|
854 | <a id="pino-stdserializers"></a>
|
855 | ### `pino.stdSerializers` (Object)
|
856 |
|
857 | The `pino.stdSerializers` object provides functions for serializing objects common to many projects. The standard serializers are directly imported from [pino-std-serializers](https://github.com/pinojs/pino-std-serializers).
|
858 |
|
859 | * See [pino-std-serializers ⇗](https://github.com/pinojs/pino-std-serializers)
|
860 |
|
861 | <a id="pino-stdtimefunctions"></a>
|
862 | ### `pino.stdTimeFunctions` (Object)
|
863 |
|
864 | The [`timestamp`](#opt-timestamp) option can accept a function which determines the
|
865 | `timestamp` value in a log line.
|
866 |
|
867 | The `pino.stdTimeFunctions` object provides a very small set of common functions for generating the
|
868 | `timestamp` property. These consist of the following
|
869 |
|
870 | * `pino.stdTimeFunctions.epochTime`: Milliseconds since Unix epoch (Default)
|
871 | * `pino.stdTimeFunctions.unixTime`: Seconds since Unix epoch
|
872 | * `pino.stdTimeFunctions.nullTime`: Clears timestamp property (Used when `timestamp: false`)
|
873 | * `pino.stdTimeFunctions.isoTime`: ISO 8601-formatted time in UTC
|
874 |
|
875 | * See [`timestamp` option](#opt-timestamp)
|
876 |
|
877 | <a id="pino-symbols"></a>
|
878 | ### `pino.symbols` (Object)
|
879 |
|
880 | For integration purposes with ecosystem and third party libraries `pino.symbols`
|
881 | exposes the symbols used to hold non-public state and methods on the logger instance.
|
882 |
|
883 | Access to the symbols allows logger state to be adjusted, and methods to be overridden or
|
884 | proxied for performant integration where necessary.
|
885 |
|
886 | The `pino.symbols` object is intended for library implementers and shouldn't be utilized
|
887 | for general use.
|
888 |
|
889 | <a id="pino-version"></a>
|
890 | ### `pino.version` (String)
|
891 |
|
892 | Exposes the Pino package version. Also available on the logger instance.
|
893 |
|
894 | * See [`logger.version`](#version)
|