Home

perj

A simple, fast JSON logger.

Goals

The perj project has the following goals:

• Designed to be integrated rather than used out of the box (DIY).
• KISS: Keep it simple smiley.
• Cross platform (Node.js and Browser) with no platform dependencies.
• Flexible log and additional property options.
• Fast.
• Feature limited.

Features

• No dependencies.
• Flexible log methods:
  • Log items can be any number in any order of any type.
• The first string is nested under the 'msg' key:
  • First string includes a string argument or an Error message.
  • Additional string arguments are nested under the data property.
• Objects are nested under the 'data' key as an object or array of objects.
• No transports included (see primary goal).

Rational

After having some performance issues with a popular Node.js logging package I decided to switch to another logger that is advertised as blasing fast called [pino][pino-url]. It's great and you should check it out.

There were a couple of things I found a little restrictive within the pino API. Specifically I wanted to be able to log content in any order without being tied down to a fixed argument list. I also wanted to ensure all extra log data was nested under a root property.

Using pino as a yard stick I created perj to meet my goals.

Function

API

These documents are not complete. Do not read below.

perj.create(options)

The create method returns a new logger object with the options applied.

options

A plain object with logger options and top level properties.

Current supported options include:

Name	Type	Default
stream	Object	process.stdout
level	string	'info'

stream: Can be set to any writable stream object that has a write function.

level: Set to one of the below values. Once set only log entries of the same or less noisy levels will be logged. If you set the level to warn you will only get fatal, error, and warn log entries.

level	lvl	When to Use
fatal	60	Stop errors. Process crash.
error	50	Processing failed for a known or unknown reason.
warn	40	Something went wrong however it is not critical.
info	30	Hey Dad? I dug a hole! (see The Castle).
debug	20	When you need to find out where something happened.
trace	10	When you need to know everything that happens.

perj.create Example

As with the quick start above, the following example adds a name, host, pid, and file as top level properties to the log entries. These properties do not exist by default because that would require perj to import the os Node.js module. Node.js modules are not imported to ease the use of perj on either Node.js or in the Browser.

const perj = require('perj')

// Customise the variables below as needed.
const name = 'QuickStart'
const host = require('os').hostname()
const pid = process.pid
const file = require('path').basename(module.filename)

// Because the valid options `level` and `stream` are not supplied they are set to the defaults.
const log = perj.create({name, host, pid, file})

log.info('the quick brown fox jumps over the lazy dog')

// The following will be sent to the process standard out
// {"ver":"1","level":"info","lvl":30,"name":"QuickStart","host":"Dev","pid":"5009","file":"example.js","time":1524902250052,"msg":"the quick brown fox jumps over the lazy dog","data":""}