@alesmenzel/churchill

1.0.0-rc.2 • Public • Published

Churchill

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

churchill logger

Installation

npm install @alesmenzel/churchill

Quick links

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.

console

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.

file

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.

Readme

Keywords

Package Sidebar

Install

npm i @alesmenzel/churchill

Weekly Downloads

1

Version

1.0.0-rc.2

License

MIT

Unpacked Size

40.1 kB

Total Files

17

Last publish

Collaborators

  • alesmenzel