Top Level Properties

Adding Top Level Properties

To document the source of JSON logs or add extended information to the logs you can add top level properties. A top level property is a key assigned to the root object within the JSON output.

It is very easy to add top level properties to your log output. Simply supply new key:value pair(s) to the options object when you create the logger. The only restriction is you can't use the key names of valid perj Options. If you do wish to use a reserved name simply nest it.

Here is an example of creating a logger with just the default options and no additional top level properties:

import Perj from 'perj'
const log = new Perj()
log.info('hello world', { foo: 'bar' })

/*

JSON result in a readable format:
{
  "level": "info",
  "lvl": 30,
  "time": 1526249898468,
  "msg": "hello world",
  "data": {
    "foo": "bar"
  }
}

*/

As you can see from the example above, only the default top level properties of 'level', 'lvl', 'time', 'msg', and 'data' are present.

This example will add a 'module' property to the JSON output:

import Perj from 'perj'
const log = new Perj({ module: 'Registration' })
log.info('hello world', { foo: 'bar' })

/*

JSON result in a readable format:
{
  "level": "info",
  "lvl": 30,
  "module": "Registration",
  "time": 1526250202223,
  "msg": "hello world",
  "data": {
    "foo": "bar"
  }
}

*/

Now you can see there is a 'module' property set to the value of 'Registration'.

You can add multiple top level properties at once. Here is an example adding format version, hostname, process id, file, and name top level properties:

import Perj from 'perj';
import os from 'os';
import path from 'path';

// Customize the variables below as needed. They are not required.
const ver = 1;
const name = 'app';
const host = os.hostname();
const pid = process.pid;
const file = path.basename(import.meta.url, '.js');

const log = new Perj({ ver, host, pid, file, name })
log.info('hello world', { foo: 'bar' })

/*

JSON result in a readable format:
{
  "level": "info",
  "lvl": 30,
  "ver": 1,
  "host": "Dev",
  "pid": 79862,
  "file": "quick.js",
  "name": "app",
  "time": 1526250630689,
  "msg": "hello world",
  "data": {
    "foo": "bar"
  }
}

*/

Now that is starting to look like a more feature rich JSON log message.

You can use any valid JSON type as the value assigned to the top level properties. Here we are nesting the platform properties under a 'platform' top level property.

import Perj from 'perj';
import os from 'os';
import path from 'path';

// Customize the variables below as needed. They are not required.
const ver = 1;
const name = 'app';
const host = os.hostname();
const pid = process.pid;
const file = path.basename(import.meta.url, '.js');
const platform = { host, pid, file }

const log = new Perj({ ver, platform, name })
log.info('hello world', { foo: 'bar' })

/*

JSON result in a readable format:
{
  "level": "info",
  "lvl": 30,
  "ver": 1,
  "platform": {
    "host": "Dev",
    "pid": 79970,
    "file": "quick.js"
  },
  "name": "app",
  "time": 1526250948299,
  "msg": "hello world",
  "data": {
    "foo": "bar"
  }
}

*/

It is worth seeing the log.child feature in action here. At the root of your application you can create a high level logger that has generic application properties. In a sub-module of the application you can further add to the root logger by using the log.child method to create a child logger from the parent. The child logger will inherit the top level properties from the parent logger and add more top level properties to it.

import Perj from 'perj'
const log = new Perj({ module: 'Registration' })
log.info('parent log message', { foo: 'bar' })

const clog = log.child({ sub: 'OAuth' })
clog.info('child log message', { foo: 'bar' })

/*

JSON result in a readable format:
{
  "level": "info",
  "lvl": 30,
  "module": "Registraion",
  "time": 1526271866030,
  "msg": "parent log message",
  "data": {
    "foo": "bar"
  }
}
{
  "level": "info",
  "lvl": 30,
  "module": "Registraion",
  "sub": "OAuth",
  "time": 1526271866032,
  "msg": "child log message",
  "data": {
    "foo": "bar"
  }
}

*/

Please checkout the separatorString option to see how you can create a hierarchical key that would look something like this. Take note of the module key:

{
  "level": "info",
  "lvl": 30,
  "module": "Registraion > Route > OAuth > Twitter",
  "time": 1526271866032,
  "msg": "child log message",
  "data": {
    "foo": "bar"
  }
}

One of the primary goals of perj is 'Designed to be integrated'. With this in mind and the flexibility of the top level properties, design your own JSON format. Give it a version so you can upgrade in the future.