1 | // Type definitions for pino 6.3
|
2 | // Project: https://github.com/pinojs/pino.git, http://getpino.io
|
3 | // Definitions by: Peter Snider <https://github.com/psnider>
|
4 | // BendingBender <https://github.com/BendingBender>
|
5 | // Christian Rackerseder <https://github.com/screendriver>
|
6 | // GP <https://github.com/paambaati>
|
7 | // Alex Ferrando <https://github.com/alferpal>
|
8 | // Oleksandr Sidko <https://github.com/mortiy>
|
9 | // Harris Lummis <https://github.com/lummish>
|
10 | // Raoul Jaeckel <https://github.com/raoulus>
|
11 | // Cory Donkin <https://github.com/Cooryd>
|
12 | // Adam Vigneaux <https://github.com/AdamVig>
|
13 | // Austin Beer <https://github.com/austin-beer>
|
14 | // Michel Nemnom <https://github.com/Pegase745>
|
15 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
16 | // TypeScript Version: 3.0
|
17 |
|
18 | /// <reference types="node"/>
|
19 |
|
20 | import stream = require("stream");
|
21 | import http = require("http");
|
22 | import { EventEmitter } from "events";
|
23 | import SonicBoom = require("sonic-boom");
|
24 | import * as pinoStdSerializers from "pino-std-serializers";
|
25 | import * as PinoPretty from "pino-pretty";
|
26 |
|
27 | export = P;
|
28 |
|
29 | /**
|
30 | * @param [optionsOrStream]: an options object or a writable stream where the logs will be written. It can also receive some log-line metadata, if the
|
31 | * relative protocol is enabled. Default: process.stdout
|
32 | * @returns a new logger instance.
|
33 | */
|
34 | declare function P(optionsOrStream?: P.LoggerOptions | P.DestinationStream): P.Logger;
|
35 |
|
36 | /**
|
37 | * @param [options]: an options object
|
38 | * @param [stream]: a writable stream where the logs will be written. It can also receive some log-line metadata, if the
|
39 | * relative protocol is enabled. Default: process.stdout
|
40 | * @returns a new logger instance.
|
41 | */
|
42 | declare function P(options: P.LoggerOptions, stream: P.DestinationStream): P.Logger;
|
43 |
|
44 | declare namespace P {
|
45 | /**
|
46 | * Holds the current log format version (as output in the v property of each log record).
|
47 | */
|
48 | const LOG_VERSION: number;
|
49 | const levels: LevelMapping;
|
50 | const symbols: {
|
51 | readonly setLevelSym: unique symbol;
|
52 | readonly getLevelSym: unique symbol;
|
53 | readonly levelValSym: unique symbol;
|
54 | readonly useLevelLabelsSym: unique symbol;
|
55 | readonly mixinSym: unique symbol;
|
56 | readonly lsCacheSym: unique symbol;
|
57 | readonly chindingsSym: unique symbol;
|
58 | readonly parsedChindingsSym: unique symbol;
|
59 | readonly asJsonSym: unique symbol;
|
60 | readonly writeSym: unique symbol;
|
61 | readonly serializersSym: unique symbol;
|
62 | readonly redactFmtSym: unique symbol;
|
63 | readonly timeSym: unique symbol;
|
64 | readonly timeSliceIndexSym: unique symbol;
|
65 | readonly streamSym: unique symbol;
|
66 | readonly stringifySym: unique symbol;
|
67 | readonly stringifiersSym: unique symbol;
|
68 | readonly endSym: unique symbol;
|
69 | readonly formatOptsSym: unique symbol;
|
70 | readonly messageKeySym: unique symbol;
|
71 | readonly nestedKeySym: unique symbol;
|
72 | readonly wildcardFirstSym: unique symbol;
|
73 | readonly needsMetadataGsym: unique symbol;
|
74 | readonly useOnlyCustomLevelsSym: unique symbol;
|
75 | readonly formattersSym: unique symbol;
|
76 | readonly hooksSym: unique symbol;
|
77 | };
|
78 | /**
|
79 | * Exposes the Pino package version. Also available on the logger instance.
|
80 | */
|
81 | const version: string;
|
82 |
|
83 | type SerializedError = pinoStdSerializers.SerializedError;
|
84 | type SerializedResponse = pinoStdSerializers.SerializedResponse;
|
85 | type SerializedRequest = pinoStdSerializers.SerializedRequest;
|
86 |
|
87 | /**
|
88 | * Provides functions for serializing objects common to many projects.
|
89 | */
|
90 | const stdSerializers: {
|
91 | /**
|
92 | * Generates a JSONifiable object from the HTTP `request` object passed to the `createServer` callback of Node's HTTP server.
|
93 | */
|
94 | req: typeof pinoStdSerializers.req;
|
95 | /**
|
96 | * Generates a JSONifiable object from the HTTP `response` object passed to the `createServer` callback of Node's HTTP server.
|
97 | */
|
98 | res: typeof pinoStdSerializers.res;
|
99 | /**
|
100 | * Serializes an Error object.
|
101 | */
|
102 | err: typeof pinoStdSerializers.err;
|
103 | /**
|
104 | * Returns an object:
|
105 | * ```
|
106 | * {
|
107 | * req: {}
|
108 | * }
|
109 | * ```
|
110 | * where req is the request as serialized by the standard request serializer.
|
111 | * @param req The request to serialize
|
112 | * @return An object
|
113 | */
|
114 | mapHttpRequest: typeof pinoStdSerializers.mapHttpRequest;
|
115 | /**
|
116 | * Returns an object:
|
117 | * ```
|
118 | * {
|
119 | * res: {}
|
120 | * }
|
121 | * ```
|
122 | * where res is the response as serialized by the standard response serializer.
|
123 | * @param res The response to serialize.
|
124 | * @return An object.
|
125 | */
|
126 | mapHttpResponse: typeof pinoStdSerializers.mapHttpResponse;
|
127 | /**
|
128 | * A utility method for wrapping the default error serializer. Allows custom serializers to work with the
|
129 | * already serialized object.
|
130 | * @param customSerializer The custom error serializer. Accepts a single parameter: the newly serialized
|
131 | * error object. Returns the new (or updated) error object.
|
132 | * @return A new error serializer.
|
133 | */
|
134 | wrapErrorSerializer: typeof pinoStdSerializers.wrapErrorSerializer;
|
135 | /**
|
136 | * A utility method for wrapping the default request serializer. Allows custom serializers to work with the
|
137 | * already serialized object.
|
138 | * @param customSerializer The custom request serializer. Accepts a single parameter: the newly serialized
|
139 | * request object. Returns the new (or updated) request object.
|
140 | * @return A new error serializer.
|
141 | */
|
142 | wrapRequestSerializer: typeof pinoStdSerializers.wrapRequestSerializer;
|
143 | /**
|
144 | * A utility method for wrapping the default response serializer. Allows custom serializers to work with the
|
145 | * already serialized object.
|
146 | * @param customSerializer The custom response serializer. Accepts a single parameter: the newly serialized
|
147 | * response object. Returns the new (or updated) response object.
|
148 | * @return A new error serializer.
|
149 | */
|
150 | wrapResponseSerializer: typeof pinoStdSerializers.wrapResponseSerializer;
|
151 | };
|
152 | /**
|
153 | * Provides functions for generating the timestamp property in the log output. You can set the `timestamp` option during
|
154 | * initialization to one of these functions to adjust the output format. Alternatively, you can specify your own time function.
|
155 | * A time function must synchronously return a string that would be a valid component of a JSON string. For example,
|
156 | * the default function returns a string like `,"time":1493426328206`.
|
157 | */
|
158 | const stdTimeFunctions: {
|
159 | /**
|
160 | * The default time function for Pino. Returns a string like `,"time":1493426328206`.
|
161 | */
|
162 | epochTime: TimeFn;
|
163 | /*
|
164 | * Returns the seconds since Unix epoch
|
165 | */
|
166 | unixTime: TimeFn;
|
167 | /**
|
168 | * Returns an empty string. This function is used when the `timestamp` option is set to `false`.
|
169 | */
|
170 | nullTime: TimeFn;
|
171 | /*
|
172 | * Returns ISO 8601-formatted time in UTC
|
173 | */
|
174 | isoTime: TimeFn;
|
175 | };
|
176 |
|
177 | /**
|
178 | * Equivalent of SonicBoom constructor options object
|
179 | */
|
180 | // TODO: use SonicBoom constructor options interface when available
|
181 | interface DestinationObjectOptions {
|
182 | fd?: string | number | undefined;
|
183 | dest?: string | undefined;
|
184 | minLength?: number | undefined;
|
185 | sync?: boolean | undefined;
|
186 | }
|
187 |
|
188 | /**
|
189 | * Create a Pino Destination instance: a stream-like object with significantly more throughput (over 30%) than a standard Node.js stream.
|
190 | * @param [dest]: The `destination` parameter, at a minimum must be an object with a `write` method. An ordinary Node.js
|
191 | * `stream` can be passed as the destination (such as the result of `fs.createWriteStream`) but for peak log
|
192 | * writing performance it is strongly recommended to use `pino.destination` to create the destination stream.
|
193 | * @returns A Sonic-Boom stream to be used as destination for the pino function
|
194 | */
|
195 | function destination(
|
196 | dest?: string | number | DestinationObjectOptions | DestinationStream | NodeJS.WritableStream,
|
197 | ): SonicBoom;
|
198 |
|
199 | /**
|
200 | * Create an extreme mode destination. This yields an additional 60% performance boost.
|
201 | * There are trade-offs that should be understood before usage.
|
202 | * @param [fileDescriptor]: File path or numerical file descriptor, by default 1
|
203 | * @returns A Sonic-Boom stream to be used as destination for the pino function
|
204 | */
|
205 | function extreme(fileDescriptor?: string | number): SonicBoom;
|
206 |
|
207 | /**
|
208 | * The pino.final method can be used to create an exit listener function.
|
209 | * This listener function can be supplied to process exit events.
|
210 | * The exit listener function will call the handler with
|
211 | * @param [logger]: pino logger that serves as reference for the final logger
|
212 | * @param [handler]: Function that will be called by the handler returned from this function
|
213 | * @returns Exit listener function that can be supplied to process exit events and will call the supplied handler function
|
214 | */
|
215 | function final(
|
216 | logger: Logger,
|
217 | handler: (error: Error, finalLogger: Logger, ...args: any[]) => void,
|
218 | ): (error: Error | null, ...args: any[]) => void;
|
219 |
|
220 | /**
|
221 | * The pino.final method can be used to acquire a final logger instance that synchronously flushes on every write.
|
222 | * @param [logger]: pino logger that serves as reference for the final logger
|
223 | * @returns Final, synchronous logger
|
224 | */
|
225 | function final(logger: Logger): Logger;
|
226 |
|
227 | interface LevelMapping {
|
228 | /**
|
229 | * Returns the mappings of level names to their respective internal number representation.
|
230 | */
|
231 | values: { [level: string]: number };
|
232 | /**
|
233 | * Returns the mappings of level internal level numbers to their string representations.
|
234 | */
|
235 | labels: { [level: number]: string };
|
236 | }
|
237 | type TimeFn = () => string;
|
238 | type MixinFn = () => object;
|
239 |
|
240 | interface DestinationStream {
|
241 | write(msg: string): void;
|
242 | }
|
243 |
|
244 | interface LoggerOptions {
|
245 | /**
|
246 | * Avoid error causes by circular references in the object tree. Default: `true`.
|
247 | */
|
248 | safe?: boolean | undefined;
|
249 | /**
|
250 | * The name of the logger. Default: `undefined`.
|
251 | */
|
252 | name?: string | undefined;
|
253 | /**
|
254 | * an object containing functions for custom serialization of objects.
|
255 | * These functions should return an JSONifiable object and they should never throw. When logging an object,
|
256 | * each top-level property matching the exact key of a serializer will be serialized using the defined serializer.
|
257 | */
|
258 | serializers?: { [key: string]: SerializerFn } | undefined;
|
259 | /**
|
260 | * Enables or disables the inclusion of a timestamp in the log message. If a function is supplied, it must
|
261 | * synchronously return a JSON string representation of the time. If set to `false`, no timestamp will be included in the output.
|
262 | * See stdTimeFunctions for a set of available functions for passing in as a value for this option.
|
263 | * Caution: any sort of formatted time will significantly slow down Pino's performance.
|
264 | */
|
265 | timestamp?: TimeFn | boolean | undefined;
|
266 | /**
|
267 | * One of the supported levels or `silent` to disable logging. Any other value defines a custom level and
|
268 | * requires supplying a level value via `levelVal`. Default: 'info'.
|
269 | */
|
270 | level?: LevelWithSilent | string | undefined;
|
271 | /**
|
272 | * Outputs the level as a string instead of integer. Default: `false`.
|
273 | */
|
274 | useLevelLabels?: boolean | undefined;
|
275 | /**
|
276 | * Changes the property `level` to any string value you pass in. Default: 'level'
|
277 | */
|
278 | levelKey?: string | undefined;
|
279 | /**
|
280 | * (DEPRECATED, use `levelKey`) Changes the property `level` to any string value you pass in. Default: 'level'
|
281 | */
|
282 | changeLevelName?: string | undefined;
|
283 | /**
|
284 | * Use this option to define additional logging levels.
|
285 | * The keys of the object correspond the namespace of the log level, and the values should be the numerical value of the level.
|
286 | */
|
287 | customLevels?: { [key: string]: number } | undefined;
|
288 | /**
|
289 | * Use this option to only use defined `customLevels` and omit Pino's levels.
|
290 | * Logger's default `level` must be changed to a value in `customLevels` in order to use `useOnlyCustomLevels`
|
291 | * Warning: this option may not be supported by downstream transports.
|
292 | */
|
293 | useOnlyCustomLevels?: boolean | undefined;
|
294 |
|
295 | /**
|
296 | * If provided, the `mixin` function is called each time one of the active logging methods
|
297 | * is called. The function must synchronously return an object. The properties of the
|
298 | * returned object will be added to the logged JSON.
|
299 | */
|
300 | mixin?: MixinFn | undefined;
|
301 |
|
302 | /**
|
303 | * As an array, the redact option specifies paths that should have their values redacted from any log output.
|
304 | *
|
305 | * Each path must be a string using a syntax which corresponds to JavaScript dot and bracket notation.
|
306 | *
|
307 | * If an object is supplied, three options can be specified:
|
308 | *
|
309 | * paths (String[]): Required. An array of paths
|
310 | * censor (String): Optional. A value to overwrite key which are to be redacted. Default: '[Redacted]'
|
311 | * remove (Boolean): Optional. Instead of censoring the value, remove both the key and the value. Default: false
|
312 | */
|
313 | redact?: string[] | redactOptions | undefined;
|
314 |
|
315 | /**
|
316 | * When defining a custom log level via level, set to an integer value to define the new level. Default: `undefined`.
|
317 | */
|
318 | levelVal?: number | undefined;
|
319 | /**
|
320 | * The string key for the 'message' in the JSON object. Default: "msg".
|
321 | */
|
322 | messageKey?: string | undefined;
|
323 | /**
|
324 | * The string key to place any logged object under.
|
325 | */
|
326 | nestedKey?: string | undefined;
|
327 | /**
|
328 | * Enables pino.pretty. This is intended for non-production configurations. This may be set to a configuration
|
329 | * object as outlined in http://getpino.io/#/docs/API?id=pretty. Default: `false`.
|
330 | */
|
331 | prettyPrint?: boolean | PrettyOptions | undefined;
|
332 | /**
|
333 | * Allows to optionally define which prettifier module to use.
|
334 | */
|
335 | // TODO: use type definitions from 'pino-pretty' when available.
|
336 | prettifier?: any;
|
337 | /**
|
338 | * This function will be invoked during process shutdown when `extreme` is set to `true`. If you do not specify
|
339 | * a function, Pino will invoke `process.exit(0)` when no error has occurred, and `process.exit(1)` otherwise.
|
340 | * If you do specify a function, it is up to you to terminate the process; you must perform only synchronous
|
341 | * operations at this point. See http://getpino.io/#/docs/extreme for more detail.
|
342 | */
|
343 | onTerminated?(eventName: string, err: any): void;
|
344 | /**
|
345 | * Enables logging. Default: `true`.
|
346 | */
|
347 | enabled?: boolean | undefined;
|
348 | /**
|
349 | * Browser only, see http://getpino.io/#/docs/browser.
|
350 | */
|
351 | browser?: {
|
352 | /**
|
353 | * The `asObject` option will create a pino-like log object instead of passing all arguments to a console
|
354 | * method. When `write` is set, `asObject` will always be true.
|
355 | *
|
356 | * @example
|
357 | * pino.info('hi') // creates and logs {msg: 'hi', level: 30, time: <ts>}
|
358 | */
|
359 | asObject?: boolean | undefined;
|
360 | /**
|
361 | * Instead of passing log messages to `console.log` they can be passed to a supplied function. If `write` is
|
362 | * set to a single function, all logging objects are passed to this function. If `write` is an object, it
|
363 | * can have methods that correspond to the levels. When a message is logged at a given level, the
|
364 | * corresponding method is called. If a method isn't present, the logging falls back to using the `console`.
|
365 | *
|
366 | * @example
|
367 | * const pino = require('pino')({
|
368 | * browser: {
|
369 | * write: (o) => {
|
370 | * // do something with o
|
371 | * }
|
372 | * }
|
373 | * })
|
374 | *
|
375 | * @example
|
376 | * const pino = require('pino')({
|
377 | * browser: {
|
378 | * write: {
|
379 | * info: function (o) {
|
380 | * //process info log object
|
381 | * },
|
382 | * error: function (o) {
|
383 | * //process error log object
|
384 | * }
|
385 | * }
|
386 | * }
|
387 | * })
|
388 | */
|
389 | write?:
|
390 | | WriteFn
|
391 | | ({
|
392 | fatal?: WriteFn | undefined;
|
393 | error?: WriteFn | undefined;
|
394 | warn?: WriteFn | undefined;
|
395 | info?: WriteFn | undefined;
|
396 | debug?: WriteFn | undefined;
|
397 | trace?: WriteFn | undefined;
|
398 | } & { [logLevel: string]: WriteFn }) | undefined;
|
399 |
|
400 | /**
|
401 | * The serializers provided to `pino` are ignored by default in the browser, including the standard
|
402 | * serializers provided with Pino. Since the default destination for log messages is the console, values
|
403 | * such as `Error` objects are enhanced for inspection, which they otherwise wouldn't be if the Error
|
404 | * serializer was enabled. We can turn all serializers on or we can selectively enable them via an array.
|
405 | *
|
406 | * When `serialize` is `true` the standard error serializer is also enabled (see
|
407 | * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#pino-stdserializers}). This is a global
|
408 | * serializer which will apply to any `Error` objects passed to the logger methods.
|
409 | *
|
410 | * If `serialize` is an array the standard error serializer is also automatically enabled, it can be
|
411 | * explicitly disabled by including a string in the serialize array: `!stdSerializers.err` (see example).
|
412 | *
|
413 | * The `serialize` array also applies to any child logger serializers (see
|
414 | * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#bindingsserializers-object} for how to
|
415 | * set child-bound serializers).
|
416 | *
|
417 | * Unlike server pino the serializers apply to every object passed to the logger method, if the `asObject`
|
418 | * option is `true`, this results in the serializers applying to the first object (as in server pino).
|
419 | *
|
420 | * For more info on serializers see
|
421 | * {@link https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object}.
|
422 | *
|
423 | * @example
|
424 | * const pino = require('pino')({
|
425 | * browser: {
|
426 | * serialize: true
|
427 | * }
|
428 | * })
|
429 | *
|
430 | * @example
|
431 | * const pino = require('pino')({
|
432 | * serializers: {
|
433 | * custom: myCustomSerializer,
|
434 | * another: anotherSerializer
|
435 | * },
|
436 | * browser: {
|
437 | * serialize: ['custom']
|
438 | * }
|
439 | * })
|
440 | * // following will apply myCustomSerializer to the custom property,
|
441 | * // but will not apply anotherSerializer to another key
|
442 | * pino.info({custom: 'a', another: 'b'})
|
443 | *
|
444 | * @example
|
445 | * const pino = require('pino')({
|
446 | * serializers: {
|
447 | * custom: myCustomSerializer,
|
448 | * another: anotherSerializer
|
449 | * },
|
450 | * browser: {
|
451 | * serialize: ['!stdSerializers.err', 'custom'] //will not serialize Errors, will serialize `custom` keys
|
452 | * }
|
453 | * })
|
454 | */
|
455 | serialize?: boolean | string[] | undefined;
|
456 |
|
457 | /**
|
458 | * Options for transmission of logs.
|
459 | *
|
460 | * @example
|
461 | * const pino = require('pino')({
|
462 | * browser: {
|
463 | * transmit: {
|
464 | * level: 'warn',
|
465 | * send: function (level, logEvent) {
|
466 | * if (level === 'warn') {
|
467 | * // maybe send the logEvent to a separate endpoint
|
468 | * // or maybe analyse the messages further before sending
|
469 | * }
|
470 | * // we could also use the `logEvent.level.value` property to determine
|
471 | * // numerical value
|
472 | * if (logEvent.level.value >= 50) { // covers error and fatal
|
473 | *
|
474 | * // send the logEvent somewhere
|
475 | * }
|
476 | * }
|
477 | * }
|
478 | * }
|
479 | * })
|
480 | */
|
481 | transmit?: {
|
482 | /**
|
483 | * Specifies the minimum level (inclusive) of when the `send` function should be called, if not supplied
|
484 | * the `send` function will be called based on the main logging `level` (set via `options.level`,
|
485 | * defaulting to `info`).
|
486 | */
|
487 | level?: Level | string | undefined;
|
488 | /**
|
489 | * Remotely record log messages.
|
490 | *
|
491 | * @description Called after writing the log message.
|
492 | */
|
493 | send: (level: Level, logEvent: LogEvent) => void;
|
494 | } | undefined;
|
495 | } | undefined;
|
496 | /**
|
497 | * key-value object added as child logger to each log line. If set to null the base child logger is not added
|
498 | */
|
499 | base?: { [key: string]: any } | null | undefined;
|
500 |
|
501 | /**
|
502 | * An object containing functions for formatting the shape of the log lines.
|
503 | * These functions should return a JSONifiable object and should never throw.
|
504 | * These functions allow for full customization of the resulting log lines.
|
505 | * For example, they can be used to change the level key name or to enrich the default metadata.
|
506 | */
|
507 | formatters?: {
|
508 | /**
|
509 | * Changes the shape of the log level.
|
510 | * The default shape is { level: number }.
|
511 | * The function takes two arguments, the label of the level (e.g. 'info') and the numeric value (e.g. 30).
|
512 | */
|
513 | level?: ((label: string, number: number) => object) | undefined;
|
514 | /**
|
515 | * Changes the shape of the bindings.
|
516 | * The default shape is { pid, hostname }.
|
517 | * The function takes a single argument, the bindings object.
|
518 | * It will be called every time a child logger is created.
|
519 | */
|
520 | bindings?: ((bindings: Bindings) => object) | undefined;
|
521 | /**
|
522 | * Changes the shape of the log object.
|
523 | * This function will be called every time one of the log methods (such as .info) is called.
|
524 | * All arguments passed to the log method, except the message, will be pass to this function.
|
525 | * By default it does not change the shape of the log object.
|
526 | */
|
527 | log?: ((object: Record<string, unknown>) => object) | undefined;
|
528 | } | undefined;
|
529 |
|
530 | /**
|
531 | * An object mapping to hook functions. Hook functions allow for customizing internal logger operations.
|
532 | * Hook functions must be synchronous functions.
|
533 | */
|
534 | hooks?: {
|
535 | /**
|
536 | * Allows for manipulating the parameters passed to logger methods. The signature for this hook is
|
537 | * logMethod (args, method, level) {}, where args is an array of the arguments that were passed to the
|
538 | * log method and method is the log method itself, and level is the log level. This hook must invoke the method function by
|
539 | * using apply, like so: method.apply(this, newArgumentsArray).
|
540 | */
|
541 | logMethod?: ((args: any[], method: LogFn, level: number) => void) | undefined;
|
542 | } | undefined;
|
543 | }
|
544 |
|
545 | // Re-export for backward compatibility
|
546 | type PrettyOptions = PinoPretty.PrettyOptions & {
|
547 | /**
|
548 | * Suppress warning on first synchronous flushing.
|
549 | */
|
550 | suppressFlushSyncWarning?: boolean | undefined;
|
551 | };
|
552 |
|
553 | type Level = "fatal" | "error" | "warn" | "info" | "debug" | "trace";
|
554 | type LevelWithSilent = Level | "silent";
|
555 |
|
556 | type SerializerFn = (value: any) => any;
|
557 | type WriteFn = (o: object) => void;
|
558 |
|
559 | /**
|
560 | * Describes a log line.
|
561 | */
|
562 | type LogDescriptor = Record<string, any>; // TODO replace `any` with `unknown` when TypeScript version >= 3.0
|
563 |
|
564 | interface Bindings {
|
565 | level?: Level | string | undefined;
|
566 | serializers?: { [key: string]: SerializerFn } | undefined;
|
567 | [key: string]: any;
|
568 | }
|
569 |
|
570 | /**
|
571 | * A data structure representing a log message, it represents the arguments passed to a logger statement, the level
|
572 | * at which they were logged and the hierarchy of child bindings.
|
573 | *
|
574 | * @description By default serializers are not applied to log output in the browser, but they will always be applied
|
575 | * to `messages` and `bindings` in the `logEvent` object. This allows us to ensure a consistent format for all
|
576 | * values between server and client.
|
577 | */
|
578 | interface LogEvent {
|
579 | /**
|
580 | * Unix epoch timestamp in milliseconds, the time is taken from the moment the logger method is called.
|
581 | */
|
582 | ts: number;
|
583 | /**
|
584 | * All arguments passed to logger method, (for instance `logger.info('a', 'b', 'c')` would result in `messages`
|
585 | * array `['a', 'b', 'c']`).
|
586 | */
|
587 | messages: any[];
|
588 | /**
|
589 | * Represents each child logger (if any), and the relevant bindings.
|
590 | *
|
591 | * @description For instance, given `logger.child({a: 1}).child({b: 2}).info({c: 3})`, the bindings array would
|
592 | * hold `[{a: 1}, {b: 2}]` and the `messages` array would be `[{c: 3}]`. The `bindings` are ordered according to
|
593 | * their position in the child logger hierarchy, with the lowest index being the top of the hierarchy.
|
594 | */
|
595 | bindings: Bindings[];
|
596 | /**
|
597 | * Holds the `label` (for instance `info`), and the corresponding numerical `value` (for instance `30`).
|
598 | * This could be important in cases where client side level values and labels differ from server side.
|
599 | */
|
600 | level: {
|
601 | label: string;
|
602 | value: number;
|
603 | };
|
604 | }
|
605 |
|
606 | type Logger = BaseLogger & { [key: string]: LogFn };
|
607 |
|
608 | interface BaseLogger extends EventEmitter {
|
609 | /**
|
610 | * Exposes the current version of Pino.
|
611 | */
|
612 | readonly pino: string;
|
613 | /**
|
614 | * Holds the current log format version (as output in the v property of each log record).
|
615 | */
|
616 | readonly LOG_VERSION: number;
|
617 | /**
|
618 | * Exposes the Pino package version. Also available on the exported pino function.
|
619 | */
|
620 | readonly version: string;
|
621 |
|
622 | levels: LevelMapping;
|
623 |
|
624 | /**
|
625 | * Set this property to the desired logging level. In order of priority, available levels are:
|
626 | *
|
627 | * - 'fatal'
|
628 | * - 'error'
|
629 | * - 'warn'
|
630 | * - 'info'
|
631 | * - 'debug'
|
632 | * - 'trace'
|
633 | *
|
634 | * The logging level is a __minimum__ level. For instance if `logger.level` is `'info'` then all `'fatal'`, `'error'`, `'warn'`,
|
635 | * and `'info'` logs will be enabled.
|
636 | *
|
637 | * You can pass `'silent'` to disable logging.
|
638 | */
|
639 | level: LevelWithSilent | string;
|
640 | /**
|
641 | * Outputs the level as a string instead of integer.
|
642 | */
|
643 | useLevelLabels: boolean;
|
644 | /**
|
645 | * Define additional logging levels.
|
646 | */
|
647 | customLevels: { [key: string]: number };
|
648 | /**
|
649 | * Use only defined `customLevels` and omit Pino's levels.
|
650 | */
|
651 | useOnlyCustomLevels: boolean;
|
652 | /**
|
653 | * Returns the integer value for the logger instance's logging level.
|
654 | */
|
655 | levelVal: number;
|
656 |
|
657 | /**
|
658 | * Registers a listener function that is triggered when the level is changed.
|
659 | * Note: When browserified, this functionality will only be available if the `events` module has been required elsewhere
|
660 | * (e.g. if you're using streams in the browser). This allows for a trade-off between bundle size and functionality.
|
661 | *
|
662 | * @param event: only ever fires the `'level-change'` event
|
663 | * @param listener: The listener is passed four arguments: `levelLabel`, `levelValue`, `previousLevelLabel`, `previousLevelValue`.
|
664 | */
|
665 | on(event: "level-change", listener: LevelChangeEventListener): this;
|
666 | addListener(event: "level-change", listener: LevelChangeEventListener): this;
|
667 | once(event: "level-change", listener: LevelChangeEventListener): this;
|
668 | prependListener(event: "level-change", listener: LevelChangeEventListener): this;
|
669 | prependOnceListener(event: "level-change", listener: LevelChangeEventListener): this;
|
670 | removeListener(event: "level-change", listener: LevelChangeEventListener): this;
|
671 |
|
672 | /**
|
673 | * Creates a child logger, setting all key-value pairs in `bindings` as properties in the log lines. All serializers will be applied to the given pair.
|
674 | * Child loggers use the same output stream as the parent and inherit the current log level of the parent at the time they are spawned.
|
675 | * From v2.x.x the log level of a child is mutable (whereas in v1.x.x it was immutable), and can be set independently of the parent.
|
676 | * If a `level` property is present in the object passed to `child` it will override the child logger level.
|
677 | *
|
678 | * @param bindings: an object of key-value pairs to include in log lines as properties.
|
679 | * @returns a child logger instance.
|
680 | */
|
681 | child(bindings: Bindings): Logger;
|
682 |
|
683 | /**
|
684 | * Log at `'fatal'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
685 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
686 | *
|
687 | * @typeParam T: the interface of the object being serialized. Default is object.
|
688 | * @param obj: object to be serialized
|
689 | * @param msg: the log message to write
|
690 | * @param ...args: format string values when `msg` is a format string
|
691 | */
|
692 | fatal: LogFn;
|
693 | /**
|
694 | * Log at `'error'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
695 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
696 | *
|
697 | * @typeParam T: the interface of the object being serialized. Default is object.
|
698 | * @param obj: object to be serialized
|
699 | * @param msg: the log message to write
|
700 | * @param ...args: format string values when `msg` is a format string
|
701 | */
|
702 | error: LogFn;
|
703 | /**
|
704 | * Log at `'warn'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
705 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
706 | *
|
707 | * @typeParam T: the interface of the object being serialized. Default is object.
|
708 | * @param obj: object to be serialized
|
709 | * @param msg: the log message to write
|
710 | * @param ...args: format string values when `msg` is a format string
|
711 | */
|
712 | warn: LogFn;
|
713 | /**
|
714 | * Log at `'info'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
715 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
716 | *
|
717 | * @typeParam T: the interface of the object being serialized. Default is object.
|
718 | * @param obj: object to be serialized
|
719 | * @param msg: the log message to write
|
720 | * @param ...args: format string values when `msg` is a format string
|
721 | */
|
722 | info: LogFn;
|
723 | /**
|
724 | * Log at `'debug'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
725 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
726 | *
|
727 | * @typeParam T: the interface of the object being serialized. Default is object.
|
728 | * @param obj: object to be serialized
|
729 | * @param msg: the log message to write
|
730 | * @param ...args: format string values when `msg` is a format string
|
731 | */
|
732 | debug: LogFn;
|
733 | /**
|
734 | * Log at `'trace'` level the given msg. If the first argument is an object, all its properties will be included in the JSON line.
|
735 | * If more args follows `msg`, these will be used to format `msg` using `util.format`.
|
736 | *
|
737 | * @typeParam T: the interface of the object being serialized. Default is object.
|
738 | * @param obj: object to be serialized
|
739 | * @param msg: the log message to write
|
740 | * @param ...args: format string values when `msg` is a format string
|
741 | */
|
742 | trace: LogFn;
|
743 | /**
|
744 | * Noop function.
|
745 | */
|
746 | silent: LogFn;
|
747 |
|
748 | /**
|
749 | * Flushes the content of the buffer in extreme mode. It has no effect if extreme mode is not enabled.
|
750 | */
|
751 | flush(): void;
|
752 |
|
753 | /**
|
754 | * A utility method for determining if a given log level will write to the destination.
|
755 | */
|
756 | isLevelEnabled(level: LevelWithSilent | string): boolean;
|
757 |
|
758 | /**
|
759 | * Returns an object containing all the current bindings, cloned from the ones passed in via logger.child().
|
760 | */
|
761 | bindings(): Bindings;
|
762 | }
|
763 |
|
764 | type LevelChangeEventListener = (
|
765 | lvl: LevelWithSilent | string,
|
766 | val: number,
|
767 | prevLvl: LevelWithSilent | string,
|
768 | prevVal: number,
|
769 | ) => void;
|
770 |
|
771 | interface LogFn {
|
772 | /* tslint:disable:no-unnecessary-generics */
|
773 | <T extends object>(obj: T, msg?: string, ...args: any[]): void;
|
774 | (msg: string, ...args: any[]): void;
|
775 | }
|
776 |
|
777 | interface redactOptions {
|
778 | paths: string[];
|
779 | censor?: string | ((v: any) => any) | undefined;
|
780 | remove?: boolean | undefined;
|
781 | }
|
782 | }
|
783 |
|
\ | No newline at end of file |