README
Roarr
Roarr CLI program provides ability to filter and pretty-print Roarr logs.
Usage
$ npm install @roarr/cli -g
$ roarr --help
Filters and formats Roarr log message.
Options:
--version Show version number [boolean]
--api-key roarr.io API key. [string]
--exclude-alien Excludes messages that cannot be recognized as
Roarr log message. [boolean] [default: false]
--filter Roarr message Liqe filter expression. [string]
--head When filtering, print a number of lines leading the
match. [number] [default: 0]
--lag When filtering, print a number of lines trailing
the match. [number] [default: 0]
--output-format [choices: "pretty", "json"] [default: "pretty"]
--use-colors Toggle use of colors in the output.
[boolean] [default: true]
--help Show help [boolean]
Viewing logs in browser
Configure --api-key
to stream logs to https://roarr.io.
export ROARR_API_KEY=00000000-0000-0000-0000-000000000000
View logs by opening https://roarr.io?room=[YOUR API KEY]
.
By default, every time you run roarr
it will generate a new stream ID and it will appear as a new source in roarr.io. However, you can configure a stable stream ID, e.g.
export ROARR_STREAM_ID=00000000-0000-0000-0000-000000000000
Identifying Log Source
By default, all @roarr/cli
agents are assigned a random name.
Agent name is used to identify the source of logs in roarr.io UI.
You can override the random name using environment variables:
export ROARR_NAME=roarr-web-app
Additionally, you can assign (comma separated) tags:
export ROARR_TAGS=production,roarr-web-app
Filtering logs
Use --filter
option to filter Roarr messages, e.g.
$ echo '
{"context":{"package":"raygun","namespace":"createHttpProxyServer","logLevel":40},"message":"internal SSL Server running on 0.0.0.0:59222","sequence":0,"time":1533310067405,"version":"1.0.0"}
{"context":{"package":"raygun","namespace":"createHttpProxyServer","logLevel":40},"message":"gracefully shutting down the proxy server","sequence":1,"time":1533310067438,"version":"1.0.0"}
{"context":{"package":"raygun","namespace":"createOnCloseEventHandler","logLevel":30},"message":"raygun server closed","sequence":2,"time":1533310067439,"version":"1.0.0"}
{"foo": "bar"}
{"context":{"package":"raygun","namespace":"createOnCloseEventHandler","logLevel":30},"message":"internal SSL close","sequence":3,"time":1533310067439,"version":"1.0.0"}
' | roarr --filter 'context.logLevel:>30'
[2018-08-03T15:27:47.405Z] WARN (40) (@raygun) (#createHttpProxyServer): internal SSL Server running on 0.0.0.0:59222
[2018-08-03T15:27:47.438Z] WARN (40) (@raygun) (#createHttpProxyServer): gracefully shutting down the proxy server
{"foo": "bar"}
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":{"package":"forward-proxy","namespace":"createHttpProxyServer","logLevel":30},"message":"Internal SSL Server running on localhost:62597","sequence":0,"time":1506803138704,"version":"1.0.0"}
{"context":{"package":"forward-proxy","namespace":"createRequestProcessor","logLevel":30},"message":"request start -> http://localhost:62595/","sequence":1,"time":1506803138741,"version":"1.0.0"}
{"context":{"package":"forward-proxy","namespace":"createLogInterceptor","logLevel":20,"headers":{"host":"localhost:62595","connection":"close"}},"message":"received request","sequence":2,"time":1506803138741,"version":"1.0.0"}
{"context":{"package":"forward-proxy","namespace":"createRequestProcessor","logLevel":30},"message":"request finished <- http://localhost:62595/","sequence":3,"time":1506803138749,"version":"1.0.0"}
{"context":{"package":"forward-proxy","namespace":"createLogInterceptor","logLevel":30,"method":"GET","requestHeaders":{"host":"localhost:62595","connection":"close"},"responseHeaders":{"date":"Sat, 30 Sep 2017 20:25:38 GMT","connection":"close","content-length":"7","x-forward-proxy-request-id":"2b746d92-1a8b-4f36-b3cc-5bff57dad94d","x-forward-proxy-cache-hit":"false"},"statusCode":200,"url":"http://localhost:62595/"},"message":"response","sequence":4,"time":1506803138755,"version":"1.0.0"}
{"context":{"package":"forward-proxy","namespace":"createLogInterceptor","logLevel":30,"method":"GET","requestHeaders":{"host":"localhost:62595","connection":"close"},"responseHeaders":{"date":"Sat, 30 Sep 2017 20:25:38 GMT","content-length":"7","x-forward-proxy-request-id":"2b746d92-1a8b-4f36-b3cc-5bff57dad94d","x-forward-proxy-cache-hit":"true"},"statusCode":200,"url":"http://localhost:62595/"},"message":"response","sequence":5,"time":1506803138762,"version":"1.0.0"}
roarr
CLI program will format the output to look like this:
@
prefixed value denotes the name of the package.#
prefixed value denotes the namespace.
The "pretty" format relies on logs using the context property names suggested in the conventions.
Roarr configuration file
Roarr searches the current working directory for .roarr.js
file. If it cannot find the configuration file, it will traverse upwards the directory tree searching for a matching configuration file and give up on a first permission error.
.roarr.js
is a JavaScript file that exports an object that defines properties used to configure Roarr, e.g.
module.exports = {
filterFunction: (message) => {
return message.context && message.context.logLevel > 20;
},
};
Supported Roarr configuration file properties
Property name | Description |
---|---|
filterFunction |
A function that receives Roarr message object and returns a boolean property that determines if the log should be filtered out (false ) or included (true ). |