@alesmenzel/churchill

Churchill

Simple to use (no overwhelming configuration) NodeJS logging utility. Inspired by winston and debug.

Installation

npm install @alesmenzel/churchill

Quick links

• Churchill
  • Installation
  • Quick links
  • Setup
  • Transports
    • Console
    • File
    • Stream
    • HTTP
  • Elastic
    • Socket
  • Customization
    • Custom Log Levels
    • Custom Formats
    • Custom transport
  • Environmental Variables
  • Logging Uncaught Exceptions
  • Contributors
  • License

Setup

Setting up Churchill is easy. Simply call churchill with a list of transports and if you are happy with the default formatting, you can use the logger in your services.

// logger.js
const churchill = require("churchill");

const { Console, File } = churchill.trasports;

const createNamespace = churchill({
  transports: [
    Console.create(),
    File.create({ filename: "error.log", maxLevel: "error" }),
    File.create({ filename: "combined.log" })
  ]
});

Here is an example service:

// worker-a.js
const logger = require('./logger')('worker:a')
logger.error('Got an error!', new Error('Err!'))
logger.warn('Ups?')
logger.info('Log me with some data!', { here: { are: 'some metadata' }})
// the default max log level is info (anything below will not be logged by default)
logger.verbose('Hello!')
logger.debug( ... )
logger.silly( ... )

The default log levels contiain 6 levels, that are ascending numerical values, where the lower the number the more important the log message is.

const LEVELS = {
  error: 0,
  warn: 1,
  info: 2, // Default maximum log level
  verbose: 3,
  debug: 4,
  silly: 5
};

Transports

This is the list of currently supported transports. Check the examples folder to see their usage. (Note that all transports are exported under churchill.trasports.<Transport>)

Name	Description	Example
Console	Log to console	Console.create({ ... })
File	Log to a file	File.create({ filename: "error.log", level: "error", ... })
Stream	Log to any arbitrary stream.	Stream.create({ stream: <Stream> })
HTTP	Log to a HTTP stream.	HTTP.create({ path: "https://domain.com/path" })
Elastic*	Log to an elasticsearch index.	Elastic.create({ node: "http://localhost:9200", index: "logs", ... })
Socket*	(*Not Implemented Yet) Log to a socket	Socket.create({ host: "127.0.0.1", port: 1337, ... })

Console

Log to a terminal. Uses chalk to colorize the output. By setting the errorLevel you can change which levels are logged to the standard error (stderr) instead of standard output (stdout). Usually best for local development.

Options:

Option	Description	Example
errorLevel	Max log level to stream to stderr	{ errorLevel: "error" }
format	Custom formatting function.	{ format: (info, out, logger) => ... }
maxLevel	Max level to log into this transport.	{ maxLevel: "warn" }

File

Log to a file on the same machine. You must specify a filename where to store the logs. Note that the folder must exists before hand.

Options:

Option	Description	Example
filename	Filename to log into	{ filename: "error.log" }
format	Custom formatting function.	{ format: (info, out, logger) => ... }
maxLevel	Max level to log into this transport.	{ maxLevel: "warn" }

Stream

Log to any arbitrary stream.

Options:

Option	Description	Example
stream	Stream to log into	{ stream: fs.createWriteStream("temp/stream.log") }
format	Custom formatting function.	{ format: (info, out, logger) => ... }
maxLevel	Max level to log into this transport.	{ maxLevel: "warn" }

HTTP

Log to a http endpoint. You must install request and request-promise-native.

npm i request request-promise-native

Options:

Option	Description	Example
method	HTTP method	{ method: "POST" }
url	URL	{ url: "https://log.example.com" }
auth	Authentication, see auth request options	{ auth: { username: "john", password: "xxxxx" } }
headers	HTTP headers	{ headers: { "Content-Type": "application/json" } }
dataKey	How to send the data (e.g. body, qs, json, form, formData). This will use the request appropriate body key, which sets required headers. Defaults to json.	{ dataKey: "form" }
format	Custom formatting function.	{ format: (info, out, logger) => ... }
maxLevel	Max level to log into this transport.	{ maxLevel: "warn" }

Elastic

In order to log to elastic, first install the elasticsearch library.

npm i @elastic/elasticsearch@7.x

Option	Description	Example
client	Elasticsearch client (or just pass a node URL)	new Client({ node: "..." })
node	Elasticsearch node URL	{ node: "http://localhost:9200" }
index	Index where to store logs.	churchill-log
format	Custom formatting function.	{ format: (info, out, logger) => ... }
maxLevel	Max level to log into this transport.	{ maxLevel: "warn" }

Socket

Not Implemented Yet (you can send a PR 😉 )

Customization

Custom Log Levels

You can also specify custom levels.

const customLevels = {
  critical: 0,
  warning: 1,
  log: 2,
  debug: 3
};

const customColors = {
  critical: "red",
  warning: "orange",
  log: "blue",
  debug: "gray"
};

churchill({ levels: customLevels, colors: customColors });

Available colors are black, red, green, yellow, blue, magenta, cyan, white, gray, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright. For more information check the chalk package.

Custom Formats

Churchill supports custom formatting functions. A formatting function accepts info (global format) or info, output, logger (transport format) objects which is the logged message, globally formatted message and the logger instance. The return value is what will be sent to transport streams.

const util = require("util");

const customGlobalFormat = info => {
  return { ...info, logger: "churchill:" };
};

const customFormat = info => {
  const { logger, namespace, timestamp, level, ms, args } = info;

  return `${logger}${namespace} ${level} ${args.map(arg => util.format(arg)).join(" ")} +${ms}ms`;
};

const createLogger = churchill({
  format: customGlobalFormat,
  transports: [Console.create({ format: customFormat })]
});

const loggerA = createLogger("worker:a");
const loggerB = createLogger("worker:b");
const loggerC = createLogger("worker:c");

loggerA.info("test", { metadata: "some info" });
// churchill:worker:a info test { metadata: 'some info' } +1ms
loggerB.info("test", { metadata: "some info" });
// churchill:worker:b info test { metadata: 'some info' } +0ms
loggerC.error("test", { metadata: "some info" });
// churchill:worker:c error test { metadata: 'some info' } +0ms

Custom transport

A transport is a class with a log method. Log method arguments are info, output and logger, where info is the object with logged message, output is formatted message by the global format function and logger is the instance that logged the message. See implementation of transports for examples.

const { Transport } = require("@alesmenzel/churchill");

// Here is a simple transport that logs to stdout and has option to provide a prefix
// Note: it does not correcly handle stream backpressure
class CustomTransport extends Transport {
  constructor(opts) {
    super(opts);
    const { prefix = "" } = opts;
    this.prefix = prefix;
  }

  /**
   * Log a Message
   * @param {Object} info Message
   * @param {*} [output] Output of the global formatting function
   * @param {Logger} logger Logger
   */
  async log(info, output, logger) {
    const out = this.format(info, output, logger);
    const prefixed = custom ? `${this.prefix}${out}` : out;
    // Transport is also an EventEmitter, so you can emit events
    if (custom) {
      this.emit("some-event", info);
    }
    process.stdout.write(prefixed); // naively log to console
  }
}

// It is recommented to provide a factory to create your logger
CustomTransport.create = opts => {
  return new CustomTransport(opts);
};

module.exports = CustomTransport;

Environmental Variables

You can change the funcionality of the logger by setting enviromental variables.

Variable	Description
CHURCHILL_DEBUG	List of enabled namespaces separated by a comma, can be also used with wildcard (i.e. worker:a*)
CHURCHILL_DEBUG_LEVEL	Max. level to log (i.e. debug)

Logging Uncaught Exceptions

Simply add listener for the uncaughtException and log whatever you need.

process.on("uncaughtException", err => {
  logger.error(err);
  // Note: if you use any asynchronous transport, you will need to wait till it is written before exiting the program
});

Contributors

Help us improve and be recognised!

Aleš Menzel 💻 📖

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

This package is developed under the MIT licence.