Skip to content

Latest commit

 

History

History
115 lines (83 loc) · 6.85 KB

api.md

File metadata and controls

115 lines (83 loc) · 6.85 KB
Raw

API

  1. laabr/laabr.plugin
    1. options
  2. laabr.token(<string> name, <Function> callback)
  3. laabr.preset(<string> key, <string|false> preset)
  4. laabr.format(<string> event, <string|false> format)

laabr/laabr.plugin

options

  • tokens: Object
    Optional. Default: {}
    It's like laabr.token(<string> name, <Function> callback). Use name/callback as key-value pairs.

  • presets: Object
    Optional. Default: {}
    It's like laabr.preset(<string> key, <string|false> preset). Use key/preset as key-value pairs.

  • formats: Object
    Optional. Default: {}
    It's like laabr.format(<string> event, <string|false> format). Use event/format as key-value pairs.

  • colored: boolean
    Optional. Default: false
    Partially colorizes token outputs with ANSI powered by chalk ⇗.

  • indent: string | number
    Optional. Default: 2
    Take a look at the space argument of JSON.stringify ⇗. This setting is just relevant for format strings marked as JSON.

  • override: boolean
    Optional. Default: false
    Override several console ⇗ logging methods with corresponding bound server.log ⇗ functions to enable logging everywhere. Keep the options.pino.level in mind which is set to info by default.

  • preformatter: Function <[data[, options]]>
    Optional. Default: (data) => data
    Preformat the originally logged message before getting processed by laabr. The function is passed the JSON object and the options as arguments and have to return an object as well. The plugin evaluates the type of the logged message just before – so it is not possible to fake an event. But have in mind that the token's return value could be affected.

  • postformatter: Function <[data[, options]]>
    Optional. Default: (data) => data
    Preformat the logged message after getting processed by laabr. The function is passed the processed string and the options as arguments and have to return a string as well.

  • handleUncaught: boolean
    Optional. Default: false
    If uncaught exception should be logged. Overrides the default behavior of Event: 'uncaughtException' ⇗ but exits the process.

Hint: If enabled it's possible that errors thrown during the processing of the plugin and its underlying plugins get hidden, e.g. in options.preformatter/options.postformatter. So if the process exits without any reason, disable this option for debugging.

  • stream: Writable
    Optional. Default: process.stdout
    Take a look at the stream argument of pino ⇗.

  • pino: Object
    Optional. Default: {}
    pino ⇗ related options. prettyPrint, timestamp and browser are effectless. The created instance is passed to hapi-pino ⇗.

  • hapiPino: Object
    Optional. Default: {}
    hapi-pino ⇗ related options. prettyPrint and instance are effectless. Use options.pino to configre the passed instance.

laabr.token(<string> name, <Function> callback)

To define a token, simply invoke laabr.token() with the name and a callback function.
Best Practise: Run laabr.token before registering the plugin.

callback(<Object> data, <Object> colors) The callback function is expected to be called with the arguments data and colors. Those represent the logged data and an object containing respective chalk ⇗ functions. Additionally, the token can accept further arguments of it's choosing to customize behavior. The colors object contains the following key: level, status and dim. Those represent chalk color functions related to the context, the log level and the request status code. This callback function is expected to return a string value. The value returned is then available as :hello in this case below:

laabr.token('hello', () => 'hello!');

Hint: disable the respective format, get the complete logged message and inspect the properties. With this it is quite easy to define custom tokens.

laabr.preset(<string> key, <string|false> preset)

To define own format presets, simply invoke laabr.preset() with an unique key and a format string. Use your own or provided presets for an easy reuse and exchange by passing the key to laabr.format() instead of the format string itself.
Best Practise: Run laabr.preset before registering the plugin.

laabr.preset('server.env', ':time :environment :host :host[port]');

laabr.format(<string> event, <string|false> format)

To define a format, simply invoke laabr.format() with the event and a format string. Use existing tokens with :<token> within the format string.
If the format is set to false, it logs the whole json message without any pretty-printed format.
Best Practise: Run laabr.format before registering the plugin.

laabr.format('onPostStart', ':time :hello world!');

Furthermore it is possible to define JSON strings. Therefor enclose the template string with { & } and use an object-like structure:

laabr.format('onPostStart', '{ ts::time, msg::hello }');

Hint: If you work with the JSON/object-like structure above and you want to work with custom strings, enclose them in quotes/backticks. If you want to concatinate tokens with custom string use a combination of + and quotes/backticks – use quotes for invalid object keys. To run inline function/methods use braces.

laabr.format('response', '{ responseTime: { value::responseTime, unit:`ms` }}');
laabr.format('response', '{ responseTime::responseTime + `ms` }');
laabr.format('response', '{ "response-time"::responseTime }');
laabr.format('response', '{ message:(JSON.stringify(:message)) }');

Or use a format preset key instead of a format string:

laabr.format('onPostStart', 'server.env');

The event is allowed to be onPostStart, onPostStop, response, request-error, log and uncaught. The events are almost analog to the hapi-pino ⇗ ones.