README.md

Roarr

A CLI program for processing Roarr logs.

• Usage
  • Filtering logs
  • Formatting logs
• .roarr.js

Usage

Install @roarr/cli and inspect all available options using roarr --help.

Filtering logs

Use --filter option to filter Roarr messages, e.g.

$ echo '
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":20},"message":"a","sequence":0,"time":1533310067405,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":30},"message":"b","sequence":1,"time":1533310067438,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":40},"message":"c","sequence":2,"time":1533310067439,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":10},"message":"d","sequence":3,"time":1533310067445,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":30},"message":"e","sequence":4,"time":1533310067459,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":40},"message":"f","sequence":5,"time":1533310067473,"version":"2.0.0"}
' | roarr --filter 'context.logLevel:>20'
[15:27:47.438]       info  @bar %foo #baz: b
[15:27:47.439]   1ms warn  @bar %foo #baz: c
[15:27:47.459]  20ms info  @bar %foo #baz: e
[15:27:47.473]  14ms warn  @bar %foo #baz: f

Refer to Liqe documentation for query syntax.

Formatting logs

Use --format-output pretty option (default) to pretty-print logs.

To format the logs, pipe the program output to roarr program, e.g.

$ ROARR_LOG=true node index.js | roarr pretty-print

Provided that the index.js program produced an output such as:

{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":20},"message":"a","sequence":0,"time":1533310067405,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":30},"message":"b","sequence":1,"time":1533310067438,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":40},"message":"c","sequence":2,"time":1533310067439,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":10},"message":"d","sequence":3,"time":1533310067445,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":30},"message":"e","sequence":4,"time":1533310067459,"version":"2.0.0"}
{"context":{"program":"foo","package":"bar","namespace":"baz","logLevel":40},"message":"f","sequence":5,"time":1533310067473,"version":"2.0.0"}

roarr CLI program will format the output to look like this:

[15:27:47.405]       debug @bar %foo #baz: a
[15:27:47.438]  33ms info  @bar %foo #baz: b
[15:27:47.439]   1ms warn  @bar %foo #baz: c
[15:27:47.445]   6ms trace @bar %foo #baz: d
[15:27:47.459]  14ms info  @bar %foo #baz: e
[15:27:47.473]  14ms warn  @bar %foo #baz: f

The "pretty" format relies on logs using the context property names suggested in the conventions:

• @ prefixed value denotes the name of the package.
• % prefixed value denotes the name of the program.
• # prefixed value denotes the namespace.

Roarr configuration file

Roarr will traverse upwards the current working directory searching for .roarr.js.

.roarr.js is a JavaScript file that exports an object that defines properties used to configure Roarr, e.g.

/** @type {import("@roarr/cli").RoarrConfiguration} */
module.exports = {
  /**
   * Receives Roarr message object and determines if to keep the log.
   */
  filter: (message) => {
    return message.context && message.context.logLevel > 20;
  },
  /**
   * List of properties (identified using dot notation) to exclude from the log message. 
   */
  omit: ['context.namespace']
};