Security News
RubyGems.org Adds New Maintainer Role
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Roarr is a lightweight and fast logger for Node.js applications. It is designed to be simple, performant, and easy to use, providing structured logging capabilities with minimal overhead.
Basic Logging
Roarr allows you to create a logger instance and log messages with different severity levels. In this example, an info message is logged.
const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.info('This is an info message');
Child Loggers
Roarr supports creating child loggers that inherit context from their parent loggers. This is useful for adding additional context to logs in different parts of your application.
const Roarr = require('roarr');
const parentLog = Roarr.child({ application: 'my-app' });
const childLog = parentLog.child({ module: 'my-module' });
childLog.debug('This is a debug message from my-module');
Structured Logging
Roarr supports structured logging, allowing you to log additional context as JSON objects. This makes it easier to analyze and search logs.
const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.info({ userId: 123, action: 'login' }, 'User login event');
Log Level Filtering
Roarr allows you to filter logs by severity level using the ROARR_LOG environment variable. In this example, only debug and higher severity logs will be output.
process.env.ROARR_LOG = 'debug';
const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.debug('This is a debug message');
log.info('This is an info message');
Winston is a versatile logging library for Node.js with support for multiple transports, log levels, and formats. It is more feature-rich compared to Roarr but also comes with more complexity and overhead.
Pino is a fast and low-overhead logging library for Node.js, similar to Roarr in terms of performance. Pino offers more features out of the box, such as log rotation and serializers, but may be slightly more complex to set up.
Bunyan is a JSON logging library for Node.js that provides structured logging and log levels. It is similar to Roarr in its focus on structured logging but includes additional features like log streams and serializers.
JSON logger for Node.js and browser.
For a long time I have been a big fan of using debug
. debug
is simple to use, works in Node.js and browser, does not require configuration and it is fast. However, problems arise when you need to parse logs. Anything but one-line text messages cannot be parsed in a safe way.
To log structured data, I have been using Winston and Bunyan. These packages are great for application-level logging. I have preferred Bunyan because of the Bunyan CLI program used to pretty-print logs. However, these packages require program-level configuration – when constructing an instance of a logger, you need to define the transport and the log-level. This makes them unsuitable for use in code designed to be consumed by other applications.
Then there is pino. pino is fast JSON logger, it has CLI program equivalent to Bunyan, it decouples transports, and it has sane default configuration. Unfortunately, you still need to instantiate logger instance at the application-level. This makes it more suitable for application-level logging just like Winston and Bunyan.
I needed a logger that:
In other words,
Roarr is this logger.
Roarr logging is disabled by default. To enable logging, you must start program with an environment variable ROARR_LOG
set to true
, e.g.
ROARR_LOG=true node ./index.js
import log from 'roarr';
log('foo');
log('bar %s', 'baz');
const debug = log.child({
logLevel: 10
});
debug('qux');
debug({
quuz: 'corge'
}, 'quux');
Produces output:
{"context":{},"message":"foo","sequence":0,"time":1506776210000,"version":"1.0.0"}
{"context":{},"message":"bar baz","sequence":1,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":10},"message":"qux","sequence":2,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":10,"quuz":"corge"},"sequence":3,"message":"quux","time":1506776210000,"version":"1.0.0"}
Roarr is designed to print all or none logs (refer to the ROARR_LOG
environment variable documentation).
To filter logs you need to use roarr filter
CLI program or a JSON processor such as jq.
jq
allows you to filter JSON messages using select(boolean_expression)
, e.g.
ROARR_LOG=true node ./index.js | jq 'select(.context.logLevel > 40)'
Combine it with roarr pretty-print
to pretty-print a subset of the logs:
ROARR_LOG=true node ./index.js | jq -cM 'select(.context.logLevel > 40)'
(Notice the use of -cM
parameters to disable JSON colarization and formatting.)
If your application outputs non-JSON output, jq will fail with an error similar to:
parse error: Invalid numeric literal at line 1, column 5
Error: write EPIPE
at _errnoException (util.js:1031:13)
at WriteWrap.afterWrite (net.js:873:14)
To ignore the non-JSON output, use jq -R
flag (raw input) in combination with fromjson
, e.g.
ROARR_LOG=true node ./index.js | jq -cRM 'fromjson? | select(.context.logLevel > 40)'
For a simplified way of filtering Roarr logs, refer to roarr filter
CLI program.
Property name | Contents |
---|---|
context | Arbitrary, user-provided structured data. See context property names. |
message | User-provided message formatted using printf. |
sequence | An incremental ID. |
time | Unix timestamp in milliseconds. |
version | Roarr log message format version. |
Example:
{
"context": {
"application": "task-runner",
"hostname": "curiosity.local",
"instanceId": "01BVBK4ZJQ182ZWF6FK4EC8FEY",
"taskId": 1
},
"message": "starting task ID 1",
"sequence": 0,
"time": 1506776210000,
"version": "1.0.0"
}
roarr
package exports a function that accepts the following API:
export type LoggerType =
(
context: MessageContextType,
message: string,
c?: SprintfArgumentType,
d?: SprintfArgumentType,
e?: SprintfArgumentType,
f?: SprintfArgumentType,
g?: SprintfArgumentType,
h?: SprintfArgumentType,
i?: SprintfArgumentType,
k?: SprintfArgumentType
) => void |
(
message: string,
b?: SprintfArgumentType,
c?: SprintfArgumentType,
d?: SprintfArgumentType,
e?: SprintfArgumentType,
f?: SprintfArgumentType,
g?: SprintfArgumentType,
h?: SprintfArgumentType,
i?: SprintfArgumentType,
k?: SprintfArgumentType
) => void;
To put it into words:
string | number | boolean | null
).Refer to the Usage documentation for common usage examples.
child
The child
function has two signatures:
Creates a child logger appending the provided context
object to the previous logger context.
type ChildType = (context: MessageContextType) => LoggerType;
Example:
import log from 'roarr';
const childLog = log.child({
foo: 'bar'
});
log.debug('foo 1');
childLog.debug('foo 2');
// {"context":{"logLevel":20},"message":"foo 1","sequence":0,"time":1531914529921,"version":"1.0.0"}
// {"context":{"foo":"bar","logLevel":20},"message":"foo 2","sequence":1,"time":1531914529922,"version":"1.0.0"}
Refer to middlewares documentation for use case examples.
Creates a child logger where every message is intercepted.
type ChildType = (translateMessage: TranslateMessageFunctionType) => LoggerType;
Example:
import log from 'roarr';
const childLog = log.child((message) => {
return {
...message,
message: message.message.replace('foo', 'bar')
}
});
log.debug('foo 1');
childLog.debug('foo 2');
// {"context":{"logLevel":20},"message":"foo 1","sequence":0,"time":1531914656076,"version":"1.0.0"}
// {"context":{"logLevel":20},"message":"bar 2","sequence":1,"time":1531914656077,"version":"1.0.0"}
Example:
trace
debug
info
warn
error
fatal
Convenience methods for logging a message with logLevel
context property value set to the name of the convenience method, e.g.
import log from 'roarr';
log.trace('foo');
log.debug('foo');
log.info('foo');
log.warn('foo');
log.error('foo');
log.fatal('foo');
Produces output:
{"context":{"logLevel":10},"message":"foo","sequence":0,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":20},"message":"foo","sequence":1,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":30},"message":"foo","sequence":2,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":40},"message":"foo","sequence":3,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":50},"message":"foo","sequence":4,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":60},"message":"foo","sequence":5,"time":1506776210000,"version":"1.0.0"}
Roarr logger supports middlewares implemented as child
message translate functions, e.g.
import log from 'roarr';
import createSerializeErrorMiddleware from '@roarr/middleware-serialize-error';
const childLog = log.child(createSerializeErrorMiddleware());
const error = new Error('foo');
log.debug({error}, 'bar');
childLog.debug({error}, 'bar');
// {"context":{"logLevel":20,"error":{}},"message":"bar","sequence":0,"time":1531918373676,"version":"1.0.0"}
// {"context":{"logLevel":20,"error":{"name":"Error","message":"foo","stack":"[REDACTED]"}},"message":"bar","sequence":1,"time":1531918373678,"version":"1.0.0"}
Roarr middlwares enable translation of every bit of information that is used to construct a log message.
The following are the official middlewares:
Raise an issue to add your middleware of your own creation.
Roarr CLI program provides ability to augment, filter and pretty-print Roarr logs.
CLI program has been moved to a separate package @roarr/cli
.
npm install @roarr/cli -g
Explore all CLI commands and options using roarr --help
or refer to @roarr/cli
documentation.
A transport in most logging libraries is something that runs in-process to perform some operation with the finalised log line. For example, a transport might send the log line to a standard syslog server after processing the log line and reformatting it.
Roarr does not support in-process transports.
Roarr does not support in-process transports because Node processes are single threaded processes (ignoring some technical details). Given this restriction, Roarr purposefully offloads handling of the logs to external processes so that the threading capabilities of the OS can be used (or other CPUs).
Depending on your configuration, consider one of the following log transports:
When running the script in a Node.js environment, use environment variables to control roarr
behaviour.
Name | Type | Function | Default |
---|---|---|---|
ROARR_LOG | Boolean | Enables/ disables logging. | false |
ROARR_STREAM | STDOUT , STDERR | Name of the stream where the logs will be written. | STDOUT |
ROARR_BUFFER_SIZE | Number | Configures the buffer size. Buffer is used to store messages before printing them to the stdout/ stderr. Recommended buffer size depends on how often program produces logs. Experiment with values 1024, 2048, 4096 and 8192. | 0 (disabled) |
When using ROARR_STREAM=STDERR
, use 3>&1 1>&2 2>&3 3>&-
to pipe stderr output.
Roarr does not have reserved context property names. However, I encourage use of the following conventions:
Context property name | Use case |
---|---|
application | Name of the application (do not use in code intended for distribution; see package property instead). |
hostname | Machine hostname. See roarr augment --append-hostname option. |
instanceId | Unique instance ID. Used to distinguish log source in high-concurrency environments. See roarr augment --append-instance-id option. |
logLevel | A numeric value indicating the log level. See API for the build-in loggers with a pre-set log-level. |
namespace | Namespace within a package, e.g. function name. Treat the same way that you would construct namespaces when using the debug package. |
package | Name of the package. |
The roarr pretty-print
CLI program is using the context property names suggested in the conventions to pretty-print the logs for the developer inspection purposes.
The roarr pretty-print
CLI program translates logLevel
values to the following human-readable names:
logLevel | Human-readable name |
---|---|
10 | TRACE |
20 | DEBUG |
30 | INFO |
40 | WARN |
50 | ERROR |
60 | FATAL |
To avoid code duplication, you can use a singleton pattern to export a logger instance with predefined context properties (e.g. describing the application).
I recommend to create a file Logger.js
in the project directory. Use this file to create an child instance of Roarr with context parameters describing the project and the initialisation instance, e.g.
/**
* @file Example contents of a Logger.js file.
*/
import log from 'roarr';
const Logger = log.child({
// .foo property is going to appear only in the logs that are created using
// the current instance of a Roarr logger.
foo: 'bar'
});
export default Logger;
Roarr does not have reserved context property names. However, I encourage use of the conventions. The roarr pretty-print
CLI program is using the context property names suggested in the conventions to pretty-print the logs for the developer inspection purposes.
This is not specific to Roarr – this suggestion applies to any kind of logging.
If you want to include an instance of Error
in the context, you must serialize the error.
The least-error prone way to do this is to use an existing library, e.g. serialize-error
.
import log from 'roarr';
import serializeError from 'serialize-error';
// [..]
send((error, result) => {
if (error) {
log.error({
error: serializeError(error)
}, 'message not sent due to a remote error');
return;
}
// [..]
});
Without using serialisation, your errors will be logged without the error name and stack trace.
If you are using Elasticsearch, you will want to create an index template.
The following serves as the ground work for the index template. It includes the main Roarr log message properties (context, message, time) and the context properties suggested in the conventions.
{
"mappings": {
"log_message": {
"_source": {
"enabled": true
},
"dynamic": "strict",
"properties": {
"context": {
"dynamic": true,
"properties": {
"application": {
"type": "keyword"
},
"hostname": {
"type": "keyword"
},
"instanceId": {
"type": "keyword"
},
"logLevel": {
"type": "integer"
},
"namespace": {
"type": "text"
},
"package": {
"type": "text"
}
}
},
"message": {
"type": "text"
},
"time": {
"format": "epoch_millis",
"type": "date"
}
}
}
},
"template": "logstash-*"
}
If your package is using Roarr, include instructions to README.md describing how to enable logging, e.g.
## Logging
This package is using [`roarr`](https://www.npmjs.com/package/roarr) logger to log the program's state.
Export `ROARR_LOG=true` environment variable to enable log printing to stdout.
Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs.
FAQs
JSON logger for Node.js and browser.
The npm package roarr receives a total of 1,041,615 weekly downloads. As such, roarr popularity was classified as popular.
We found that roarr demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.