1 | <a id="intro"></a>
|
2 | # pino-pretty
|
3 |
|
4 | [![Build Status](https://travis-ci.org/pinojs/pino-pretty.svg?branch=master)](https://travis-ci.org/pinojs/pino-pretty)
|
5 | [![Coverage Status](https://coveralls.io/repos/github/pinojs/pino-pretty/badge.svg?branch=master)](https://coveralls.io/github/pinojs/pino-pretty?branch=master)
|
6 |
|
7 | This module provides a basic [ndjson](http://ndjson.org/) formatter. If an
|
8 | incoming line looks like it could be a log line from an ndjson logger, in
|
9 | particular the [Pino](https://getpino.io/) logging library, then it will apply
|
10 | extra formatting by considering things like the log level and timestamp.
|
11 |
|
12 | A standard Pino log line like:
|
13 |
|
14 | ```
|
15 | {"level":30,"time":1522431328992,"msg":"hello world","pid":42,"hostname":"foo","v":1}
|
16 | ```
|
17 |
|
18 | Will format to:
|
19 |
|
20 | ```
|
21 | [1522431328992] INFO (42 on foo): hello world
|
22 | ```
|
23 |
|
24 | <a id="example"></a>
|
25 | ## Example
|
26 |
|
27 | Using the [example script][exscript] from the Pino module, and specifying
|
28 | that logs should be colored and the time translated, we can see what the
|
29 | prettified logs will look like:
|
30 |
|
31 | ![demo](demo.png)
|
32 |
|
33 | [exscript]: https://github.com/pinojs/pino/blob/fc4c83b/example.js
|
34 |
|
35 | <a id="install"></a>
|
36 | ## Install
|
37 |
|
38 | ```sh
|
39 | $ npm install -g pino-pretty
|
40 | ```
|
41 |
|
42 | <a id="usage"></a>
|
43 | ## Usage
|
44 |
|
45 | It's recommended to use `pino-pretty` with `pino`
|
46 | by piping output to the CLI tool:
|
47 |
|
48 | ```sh
|
49 | pino app.js | pino-pretty
|
50 | ```
|
51 |
|
52 | <a id="cliargs"></a>
|
53 | ### CLI Arguments
|
54 |
|
55 | - `--colorize` (`-c`): Adds terminal color escape sequences to the output.
|
56 | - `--crlf` (`-f`): Appends carriage return and line feed, instead of just a line
|
57 | feed, to the formatted log line.
|
58 | - `--errorProps` (`-e`): When formatting an error object, display this list
|
59 | of properties. The list should be a comma separated list of properties Default: `''`.
|
60 | - `--levelFirst` (`-l`): Display the log level name before the logged date and time.
|
61 | - `--errorLikeObjectKeys` (`-k`): Define the log keys that are associated with
|
62 | error like objects. Default: `err,error`.
|
63 | - `--messageKey` (`-m`): Define the key that contains the main log message.
|
64 | Default: `msg`.
|
65 | - `--messageFormat` (`-o`): Format output of message, e.g. `{level} - {pid}` will output message: `INFO - 1123`
|
66 | Default: `false`
|
67 | - `--timestampKey` (`-m`): Define the key that contains the log timestamp.
|
68 | Default: `time`.
|
69 | - `--translateTime` (`-t`): Translate the epoch time value into a human readable
|
70 | date and time string. This flag also can set the format string to apply when
|
71 | translating the date to human readable format. For a list of available pattern
|
72 | letters see the [`dateformat` documentation](https://www.npmjs.com/package/dateformat).
|
73 | - The default format is `yyyy-mm-dd HH:MM:ss.l o` in UTC.
|
74 | - Require a `SYS:` prefix to translate time to the local system's timezone. A
|
75 | shortcut `SYS:standard` to translate time to `yyyy-mm-dd HH:MM:ss.l o` in
|
76 | system timezone.
|
77 | - `--search` (`-s`): Specify a search pattern according to
|
78 | [jmespath](http://jmespath.org/).
|
79 | - `--ignore` (`-i`): Ignore one or several keys: (`-i time,hostname`)
|
80 | - `--config`: Specify a path to a config file containing the pino-pretty options. pino-pretty will attempt to read from a `.pino-prettyrc` in your current directory (`process.cwd`) if not specified
|
81 |
|
82 | <a id="integration"></a>
|
83 | ## Programmatic Integration
|
84 |
|
85 | We recommend against using `pino-pretty` in production, and highly
|
86 | recommend installing `pino-pretty` as a development dependency.
|
87 |
|
88 | When installed, `pino-pretty` will be used by `pino` as the default
|
89 | prettifier.
|
90 |
|
91 | Install `pino-pretty` alongside `pino` and set the
|
92 | `prettyPrint` option to `true`:
|
93 |
|
94 | ```js
|
95 | const pino = require('pino')
|
96 | const logger = pino({
|
97 | prettyPrint: true
|
98 | })
|
99 |
|
100 | logger.info('hi')
|
101 | ```
|
102 |
|
103 | The `prettyPrint` option can also be an object containing `pretty-print`
|
104 | options:
|
105 |
|
106 | ```js
|
107 | const pino = require('pino')
|
108 | const logger = pino({
|
109 | prettyPrint: { colorize: true }
|
110 | })
|
111 |
|
112 | logger.info('hi')
|
113 | ```
|
114 |
|
115 | See the [Options](#options) section for all possible options.
|
116 |
|
117 | <a id="options"></a>
|
118 | ### Options
|
119 |
|
120 | `pino-pretty` exports a factory function that can be used to format log strings.
|
121 | This factory function is used internally by Pino, and accepts an options argument
|
122 | with keys corresponding to the options described in [CLI Arguments](#cliargs):
|
123 |
|
124 | ```js
|
125 | {
|
126 | colorize: chalk.supportsColor, // --colorize
|
127 | crlf: false, // --crlf
|
128 | errorLikeObjectKeys: ['err', 'error'], // --errorLikeObjectKeys
|
129 | errorProps: '', // --errorProps
|
130 | levelFirst: false, // --levelFirst
|
131 | messageKey: 'msg', // --messageKey
|
132 | messageFormat: false // --messageFormat
|
133 | timestampKey: 'time', // --timestampKey
|
134 | translateTime: false, // --translateTime
|
135 | search: 'foo == `bar`', // --search
|
136 | ignore: 'pid,hostname' // --ignore,
|
137 | customPrettifiers: {}
|
138 | }
|
139 | ```
|
140 |
|
141 | The `colorize` default follows
|
142 | [`chalk.supportsColor`](https://www.npmjs.com/package/chalk#chalksupportscolor).
|
143 |
|
144 | `customPrettifiers` option provides the ability to add a custom prettify function
|
145 | for specific log properties. `customPrettifiers` is an object, where keys are
|
146 | log properties which will be prettified and value is the prettify function itself.
|
147 | For example, if a log line contains a `query` property,
|
148 | you can specify a prettifier for it:
|
149 | ```js
|
150 | {
|
151 | customPrettifiers: {
|
152 | query: prettifyQuery
|
153 | }
|
154 | }
|
155 | //...
|
156 | const prettifyQuery = value => {
|
157 | // do some prettify magic
|
158 | }
|
159 | ```
|
160 |
|
161 | <a id="license"><a>
|
162 | ## License
|
163 |
|
164 | MIT License
|