You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
200 lines
6.2 KiB
200 lines
6.2 KiB
4 years ago
|
# Browser API
|
||
|
|
||
|
Pino is compatible with [`browserify`](http://npm.im/browserify) for browser side usage:
|
||
|
|
||
|
This can be useful with isomorphic/universal JavaScript code.
|
||
|
|
||
|
By default, in the browser,
|
||
|
`pino` uses corresponding [Log4j](https://en.wikipedia.org/wiki/Log4j) `console` methods (`console.error`, `console.warn`, `console.info`, `console.debug`, `console.trace`) and uses `console.error` for any `fatal` level logs.
|
||
|
|
||
|
## Options
|
||
|
|
||
|
Pino can be passed a `browser` object in the options object,
|
||
|
which can have the following properties:
|
||
|
|
||
|
### `asObject` (Boolean)
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({browser: {asObject: true}})
|
||
|
```
|
||
|
|
||
|
The `asObject` option will create a pino-like log object instead of
|
||
|
passing all arguments to a console method, for instance:
|
||
|
|
||
|
```js
|
||
|
pino.info('hi') // creates and logs {msg: 'hi', level: 30, time: <ts>}
|
||
|
```
|
||
|
|
||
|
When `write` is set, `asObject` will always be `true`.
|
||
|
|
||
|
### `write` (Function | Object)
|
||
|
|
||
|
Instead of passing log messages to `console.log` they can be passed to
|
||
|
a supplied function.
|
||
|
|
||
|
If `write` is set to a single function, all logging objects are passed
|
||
|
to this function.
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
browser: {
|
||
|
write: (o) => {
|
||
|
// do something with o
|
||
|
}
|
||
|
}
|
||
|
})
|
||
|
```
|
||
|
|
||
|
If `write` is an object, it can have methods that correspond to the
|
||
|
levels. When a message is logged at a given level, the corresponding
|
||
|
method is called. If a method isn't present, the logging falls back
|
||
|
to using the `console`.
|
||
|
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
browser: {
|
||
|
write: {
|
||
|
info: function (o) {
|
||
|
//process info log object
|
||
|
},
|
||
|
error: function (o) {
|
||
|
//process error log object
|
||
|
}
|
||
|
}
|
||
|
}
|
||
|
})
|
||
|
```
|
||
|
|
||
|
### `serialize`: (Boolean | Array)
|
||
|
|
||
|
The serializers provided to `pino` are ignored by default in the browser, including
|
||
|
the standard serializers provided with Pino. Since the default destination for log
|
||
|
messages is the console, values such as `Error` objects are enhanced for inspection,
|
||
|
which they otherwise wouldn't be if the Error serializer was enabled.
|
||
|
|
||
|
We can turn all serializers on,
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
browser: {
|
||
|
serialize: true
|
||
|
}
|
||
|
})
|
||
|
```
|
||
|
|
||
|
Or we can selectively enable them via an array:
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
serializers: {
|
||
|
custom: myCustomSerializer,
|
||
|
another: anotherSerializer
|
||
|
},
|
||
|
browser: {
|
||
|
serialize: ['custom']
|
||
|
}
|
||
|
})
|
||
|
// following will apply myCustomSerializer to the custom property,
|
||
|
// but will not apply anotherSerializer to another key
|
||
|
pino.info({custom: 'a', another: 'b'})
|
||
|
```
|
||
|
|
||
|
When `serialize` is `true` the standard error serializer is also enabled (see https://github.com/pinojs/pino/blob/master/docs/api.md#stdSerializers).
|
||
|
This is a global serializer which will apply to any `Error` objects passed to the logger methods.
|
||
|
|
||
|
If `serialize` is an array the standard error serializer is also automatically enabled, it can
|
||
|
be explicitly disabled by including a string in the serialize array: `!stdSerializers.err`, like so:
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
serializers: {
|
||
|
custom: myCustomSerializer,
|
||
|
another: anotherSerializer
|
||
|
},
|
||
|
browser: {
|
||
|
serialize: ['!stdSerializers.err', 'custom'] //will not serialize Errors, will serialize `custom` keys
|
||
|
}
|
||
|
})
|
||
|
```
|
||
|
|
||
|
The `serialize` array also applies to any child logger serializers (see https://github.com/pinojs/pino/blob/master/docs/api.md#discussion-2
|
||
|
for how to set child-bound serializers).
|
||
|
|
||
|
Unlike server pino the serializers apply to every object passed to the logger method,
|
||
|
if the `asObject` option is `true`, this results in the serializers applying to the
|
||
|
first object (as in server pino).
|
||
|
|
||
|
For more info on serializers see https://github.com/pinojs/pino/blob/master/docs/api.md#parameters.
|
||
|
|
||
|
### `transmit` (Object)
|
||
|
|
||
|
An object with `send` and `level` properties.
|
||
|
|
||
|
The `transmit.level` property specifies the minimum level (inclusive) of when the `send` function
|
||
|
should be called, if not supplied the `send` function be called based on the main logging `level`
|
||
|
(set via `options.level`, defaulting to `info`).
|
||
|
|
||
|
The `transmit` object must have a `send` function which will be called after
|
||
|
writing the log message. The `send` function is passed the level of the log
|
||
|
message and a `logEvent` object.
|
||
|
|
||
|
The `logEvent` object is a data structure representing a log message, it represents
|
||
|
the arguments passed to a logger statement, the level
|
||
|
at which they were logged and the hierarchy of child bindings.
|
||
|
|
||
|
The `logEvent` format is structured like so:
|
||
|
|
||
|
```js
|
||
|
{
|
||
|
ts = Number,
|
||
|
messages = Array,
|
||
|
bindings = Array,
|
||
|
level: { label = String, value = Number}
|
||
|
}
|
||
|
```
|
||
|
|
||
|
The `ts` property is a unix epoch timestamp in milliseconds, the time is taken from the moment the
|
||
|
logger method is called.
|
||
|
|
||
|
The `messages` array is all arguments passed to logger method, (for instance `logger.info('a', 'b', 'c')`
|
||
|
would result in `messages` array `['a', 'b', 'c']`).
|
||
|
|
||
|
The `bindings` array represents each child logger (if any), and the relevant bindings.
|
||
|
For instance given `logger.child({a: 1}).child({b: 2}).info({c: 3})`, the bindings array
|
||
|
would hold `[{a: 1}, {b: 2}]` and the `messages` array would be `[{c: 3}]`. The `bindings`
|
||
|
are ordered according to their position in the child logger hierarchy, with the lowest index
|
||
|
being the top of the hierarchy.
|
||
|
|
||
|
By default serializers are not applied to log output in the browser, but they will *always* be
|
||
|
applied to `messages` and `bindings` in the `logEvent` object. This allows us to ensure a consistent
|
||
|
format for all values between server and client.
|
||
|
|
||
|
The `level` holds the label (for instance `info`), and the corresponding numerical value
|
||
|
(for instance `30`). This could be important in cases where client side level values and
|
||
|
labels differ from server side.
|
||
|
|
||
|
The point of the `send` function is to remotely record log messages:
|
||
|
|
||
|
```js
|
||
|
const pino = require('pino')({
|
||
|
browser: {
|
||
|
transmit: {
|
||
|
level: 'warn',
|
||
|
send: function (level, logEvent) {
|
||
|
if (level === 'warn') {
|
||
|
// maybe send the logEvent to a separate endpoint
|
||
|
// or maybe analyse the messages further before sending
|
||
|
}
|
||
|
// we could also use the `logEvent.level.value` property to determine
|
||
|
// numerical value
|
||
|
if (logEvent.level.value >= 50) { // covers error and fatal
|
||
|
|
||
|
// send the logEvent somewhere
|
||
|
}
|
||
|
}
|
||
|
}
|
||
|
}
|
||
|
})
|
||
|
```
|