strong-tie/inbound-calls

1# Browser API2 3Pino is compatible with [`browserify`](https://npm.im/browserify) for browser-side usage:4 5This can be useful with isomorphic/universal JavaScript code.6 7By default, in the browser,8`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.9 10## Options11 12Pino can be passed a `browser` object in the options object,13which can have the following properties:14 15### `asObject` (Boolean)16 17```js18const pino = require('pino')({browser: {asObject: true}})19```20 21The `asObject` option will create a pino-like log object instead of22passing all arguments to a console method, for instance:23 24```js25pino.info('hi') // creates and logs {msg: 'hi', level: 30, time: <ts>}26```27 28When `write` is set, `asObject` will always be `true`.29 30### `formatters` (Object)31 32An object containing functions for formatting the shape of the log lines. When provided, it enables the logger to produce a pino-like log object with customized formatting. Currently, it supports formatting for the `level` object only.33 34##### `level`35 36Changes the shape of the log level. The default shape is `{ level: number }`.37The function takes two arguments, the label of the level (e.g. `'info'`)38and the numeric value (e.g. `30`).39 40```js41const formatters = {42  level (label, number) {43    return { level: number }44  }45}46```47 48 49### `write` (Function | Object)50 51Instead of passing log messages to `console.log` they can be passed to52a supplied function.53 54If `write` is set to a single function, all logging objects are passed55to this function.56 57```js58const pino = require('pino')({59  browser: {60    write: (o) => {61      // do something with o62    }63  }64})65```66 67If `write` is an object, it can have methods that correspond to the68levels. When a message is logged at a given level, the corresponding69method is called. If a method isn't present, the logging falls back70to using the `console`.71 72 73```js74const pino = require('pino')({75  browser: {76    write: {77      info: function (o) {78        //process info log object79      },80      error: function (o) {81        //process error log object82      }83    }84  }85})86```87 88### `serialize`: (Boolean | Array)89 90The serializers provided to `pino` are ignored by default in the browser, including91the standard serializers provided with Pino. Since the default destination for log92messages is the console, values such as `Error` objects are enhanced for inspection,93which they otherwise wouldn't be if the Error serializer was enabled.94 95We can turn all serializers on,96 97```js98const pino = require('pino')({99  browser: {100    serialize: true101  }102})103```104 105Or we can selectively enable them via an array:106 107```js108const pino = require('pino')({109  serializers: {110    custom: myCustomSerializer,111    another: anotherSerializer112  },113  browser: {114    serialize: ['custom']115  }116})117// following will apply myCustomSerializer to the custom property,118// but will not apply anotherSerializer to another key119pino.info({custom: 'a', another: 'b'})120```121 122When `serialize` is `true` the standard error serializer is also enabled (see https://github.com/pinojs/pino/blob/master/docs/api.md#stdSerializers).123This is a global serializer, which will apply to any `Error` objects passed to the logger methods.124 125If `serialize` is an array the standard error serializer is also automatically enabled, it can126be explicitly disabled by including a string in the serialize array: `!stdSerializers.err`, like so:127 128```js129const pino = require('pino')({130  serializers: {131    custom: myCustomSerializer,132    another: anotherSerializer133  },134  browser: {135    serialize: ['!stdSerializers.err', 'custom'] //will not serialize Errors, will serialize `custom` keys136  }137})138```139 140The `serialize` array also applies to any child logger serializers (see https://github.com/pinojs/pino/blob/master/docs/api.md#discussion-2141for how to set child-bound serializers).142 143Unlike server pino the serializers apply to every object passed to the logger method,144if the `asObject` option is `true`, this results in the serializers applying to the145first object (as in server pino).146 147For more info on serializers see https://github.com/pinojs/pino/blob/master/docs/api.md#mergingobject.148 149### `transmit` (Object)150 151An object with `send` and `level` properties.152 153The `transmit.level` property specifies the minimum level (inclusive) of when the `send` function154should be called, if not supplied the `send` function be called based on the main logging `level`155(set via `options.level`, defaulting to `info`).156 157The `transmit` object must have a `send` function which will be called after158writing the log message. The `send` function is passed the level of the log159message and a `logEvent` object.160 161The `logEvent` object is a data structure representing a log message, it represents162the arguments passed to a logger statement, the level163at which they were logged, and the hierarchy of child bindings.164 165The `logEvent` format is structured like so:166 167```js168{169  ts = Number,170  messages = Array,171  bindings = Array,172  level: { label = String, value = Number}173}174```175 176The `ts` property is a Unix epoch timestamp in milliseconds, the time is taken from the moment the177logger method is called.178 179The `messages` array is all arguments passed to logger method, (for instance `logger.info('a', 'b', 'c')`180would result in `messages` array `['a', 'b', 'c']`).181 182The `bindings` array represents each child logger (if any), and the relevant bindings.183For instance, given `logger.child({a: 1}).child({b: 2}).info({c: 3})`, the bindings array184would hold `[{a: 1}, {b: 2}]` and the `messages` array would be `[{c: 3}]`. The `bindings`185are ordered according to their position in the child logger hierarchy, with the lowest index186being the top of the hierarchy.187 188By default, serializers are not applied to log output in the browser, but they will *always* be189applied to `messages` and `bindings` in the `logEvent` object. This allows us to ensure a consistent190format for all values between server and client.191 192The `level` holds the label (for instance `info`), and the corresponding numerical value193(for instance `30`). This could be important in cases where client-side level values and194labels differ from server-side.195 196The point of the `send` function is to remotely record log messages:197 198```js199const pino = require('pino')({200  browser: {201    transmit: {202      level: 'warn',203      send: function (level, logEvent) {204        if (level === 'warn') {205          // maybe send the logEvent to a separate endpoint206          // or maybe analyze the messages further before sending207        }208        // we could also use the `logEvent.level.value` property to determine209        // numerical value210        if (logEvent.level.value >= 50) { // covers error and fatal211 212          // send the logEvent somewhere213        }214      }215    }216  }217})218```219 220### `disabled` (Boolean)221 222```js223const pino = require('pino')({browser: {disabled: true}})224```225 226The `disabled` option will disable logging in browser if set227to `true`, by default it is set to `false`.228