log4js-node

A port of log4js to node.js

View the Project on GitHub

Layouts

Layouts are functions used by appenders to format log events for output. They take a log event as an argument and return a string. Log4js comes with several appenders built-in, and provides ways to create your own if these are not suitable.

For most use cases you will not need to configure layouts - there are some appenders which do not need layouts defined (for example, logFaces-UDP); all the appenders that use layouts will have a sensible default defined.

Configuration

Most appender configuration will take a field called layout, which is an object - typically with a single field type which is the name of a layout defined below. Some layouts require extra configuration options, which should be included in the same object.

Example

log4js.configure({
  appenders: { out: { type: "stdout", layout: { type: "basic" } } },
  categories: { default: { appenders: ["out"], level: "info" } },
});

This configuration replaces the stdout appender’s default coloured layout with basic layout.

Built-in Layouts

Basic

Basic layout will output the timestamp, level, category, followed by the formatted log event data.

Example

log4js.configure({
  appenders: { out: { type: "stdout", layout: { type: "basic" } } },
  categories: { default: { appenders: ["out"], level: "info" } },
});
const logger = log4js.getLogger("cheese");
logger.error("Cheese is too ripe!");

This will output:

[2017-03-30 07:57:00.113] [ERROR] cheese - Cheese is too ripe!

Coloured

This layout is the same as basic, except that the timestamp, level and category will be coloured according to the log event’s level (if your terminal/file supports it - if you see some weird characters in your output and no colour then you should probably switch to basic). The colours used are:

Message Pass-Through

This layout just formats the log event data, and does not output a timestamp, level or category. It is typically used in appenders that serialise the events using a specific format (e.g. gelf).

Example

log4js.configure({
  appenders: {
    out: { type: "stdout", layout: { type: "messagePassThrough" } },
  },
  categories: { default: { appenders: ["out"], level: "info" } },
});
const logger = log4js.getLogger("cheese");
const cheeseName = "gouda";
logger.error("Cheese is too ripe! Cheese was: ", cheeseName);

This will output:

Cheese is too ripe! Cheese was: gouda

Dummy

This layout only outputs the first value in the log event’s data. It was added for the logstashUDP appender, and I’m not sure there’s much use for it outside that.

Example

log4js.configure({
  appenders: { out: { type: "stdout", layout: { type: "dummy" } } },
  categories: { default: { appenders: ["out"], level: "info" } },
});
const logger = log4js.getLogger("cheese");
const cheeseName = "gouda";
logger.error("Cheese is too ripe! Cheese was: ", cheeseName);

This will output:

Cheese is too ripe! Cheese was:

Pattern

Pattern format

The pattern string can contain any characters, but sequences beginning with % will be replaced with values taken from the log event, and other environmental values. Format for specifiers is %[padding].[truncation][field]{[format]} - padding and truncation are optional, and format only applies to a few tokens (notably, date). Both padding and truncation values can be negative.

e.g. %5.10p - left pad the log level by up to 5 characters, keep the whole string to a max length of 10. So, for a log level of INFO the output would be “ INFO”, for DEBUG it would be “DEBUG” and for a (custom) log level of CATASTROPHIC it would be “CATASTROPH”.

Fields can be any of:

Tokens

User-defined tokens can be either a string or a function. Functions will be passed the log event, and should return a string. For example, you could define a custom token that outputs the log event’s context value for ‘user’ like so:

log4js.configure({
  appenders: {
    out: {
      type: "stdout",
      layout: {
        type: "pattern",
        pattern: "%d %p %c %x{user} %m%n",
        tokens: {
          user: function (logEvent) {
            return AuthLibrary.currentUser();
          },
        },
      },
    },
  },
  categories: { default: { appenders: ["out"], level: "info" } },
});
const logger = log4js.getLogger();
logger.info("doing something.");

This would output:

2017-06-01 08:32:56.283 INFO default charlie doing something.

You can also use the Logger context to store tokens (sometimes called Nested Diagnostic Context, or Mapped Diagnostic Context) and use them in your layouts.

log4js.configure({
  appenders: {
    out: {
      type: "stdout",
      layout: {
        type: "pattern",
        pattern: "%d %p %c %X{user} %m%n",
      },
    },
  },
  categories: { default: { appenders: ["out"], level: "info" } },
});
const logger = log4js.getLogger();
logger.addContext("user", "charlie");
logger.info("doing something.");

This would output:

2017-06-01 08:32:56.283 INFO default charlie doing something.

Note that you can also add functions to the Logger Context, and they will be passed the logEvent as well.

Adding your own layouts

You can add your own layouts by calling log4js.addLayout(type, fn) before calling log4js.configure. type is the label you want to use to refer to your layout in appender configuration. fn is a function that takes a single object argument, which will contain the configuration for the layout instance, and returns a layout function. A layout function takes a log event argument and returns a string (usually, although you could return anything as long as the appender knows what to do with it).

Custom Layout Example

This example can also be found in examples/custom-layout.js.

const log4js = require("log4js");

log4js.addLayout("json", function (config) {
  return function (logEvent) {
    return JSON.stringify(logEvent) + config.separator;
  };
});

log4js.configure({
  appenders: {
    out: { type: "stdout", layout: { type: "json", separator: "," } },
  },
  categories: {
    default: { appenders: ["out"], level: "info" },
  },
});

const logger = log4js.getLogger("json-test");
logger.info("this is just a test");
logger.error("of a custom appender");
logger.warn("that outputs json");
log4js.shutdown(() => {});

This example outputs the following:

{"startTime":"2017-06-05T22:23:08.479Z","categoryName":"json-test","data":["this is just a test"],"level":{"level":20000,"levelStr":"INFO"},"context":{}},
{"startTime":"2017-06-05T22:23:08.483Z","categoryName":"json-test","data":["of a custom appender"],"level":{"level":40000,"levelStr":"ERROR"},"context":{}},
{"startTime":"2017-06-05T22:23:08.483Z","categoryName":"json-test","data":["that outputs json"],"level":{"level":30000,"levelStr":"WARN"},"context":{}},