Logging from Node.js

Logging with Winston

Winston is a popular node.js logging library with support for structured logging. Winston uses 'transports' to represent different log destinations including the usual console and file options. winston-seq is a Winston transport that allows Winston to write to Seq.

Getting started

npm install @datalust/winston-seq winston

Configuration

Minimal example:

const winston = require('winston');
const { SeqTransport } = require('@datalust/winston-seq');

const logger = winston.createLogger({
  transports: [
    new SeqTransport({
      serverUrl: "https://your-seq-server:5341",
      apiKey: "your-api-key",
      onError: (e => { console.error(e) }),
    })
  ]
});

Configuration with typical options:

const winston = require('winston');
const { SeqTransport } = require('@datalust/winston-seq');
// or import { SeqTransport } from '@datalust/winston-seq';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(  /* This is required to get errors to log with stack traces. See https://github.com/winstonjs/winston/issues/1498 */
    winston.format.errors({ stack: true }),
    winston.format.json(),
  ),
  defaultMeta: { /* application: 'your-app-name' */ },
  transports: [
    new winston.transports.Console({
        format: winston.format.simple(),
    }),
    new SeqTransport({
      serverUrl: "https://your-seq-server:5341",
      apiKey: "your-api-key",
      onError: (e => { console.error(e) }),
      handleExceptions: true,
      handleRejections: true,
    })
  ]
});

serverUrl - the URL for your Seq server's ingestion
apiKey - (optional) The Seq API Key to use
onError - Callback to execute when an error occurs within the transport
handleExceptions - (optional) Send an event when an uncaught exception occurs
handleRejections - (optional) Send an event when an unhandled promise rejection occurs

Send log events

Send structured log events, with properties that can be used later for filtering and analysis:

logger.info("Hello {name}", {name: "World"});

Attach context by creating child loggers:

const taskLogger = logger.child({ activity: "purchase" });
taskLogger.debug(
    "User {user} purchase product {product} at ${price}", 
    {
        user: "Millie Gilbert",
        product: "Yardtime Garden Shears",
        price: 29.99
    });

2560 — A structured log event from Winston and winston-seq

Logging with Bunyan

The Bunyan library is a logger for JavaScript with wide platform support and good facilities for structured log messages. The bunyan-seq package is a plug-in for Bunyan that batches log events and posts the to the Seq HTTP ingestion API.

Getting started

First, install both the bunyan and bunyan-seq packages.

npm install --save bunyan
npm install --save bunyan-seq

Configuration

When configuring the Bunyan logger, pass a Seq stream using createStream():

let bunyan = require('bunyan');
let seq = require('bunyan-seq');

var log = bunyan.createLogger({
    name: 'myapp',
    streams: [
        {
            stream: process.stdout,
            level: 'warn',
        },
        seq.createStream({
            serverUrl: 'http://localhost:5341',
            level: 'info'
        })
    ]
});

log.info('Hi!');
log.warn({lang: 'fr'}, 'Au revoir');

The createStream() method accepts a configuration object with the following parameters. No parameters are required.

Parameter	Default	Description
`apiKey`		The API Key to use when connecting to Seq
`batchSizeLimit`	1048576 (1 MiB)	The maximum batch size to send to Seq (should not exceed Settings > System > Raw ingestion payload limit)
`eventSizeLimit`	262144 (256 kiB)	The maximum event size to send to Seq; larger events will be dumped to stdout (should match Settings > System > Raw event body limit)
`level`		The Bunyan logging level for the stream
`maxBatchingTime`	2000	The time in milliseconds that the logger will wait for additional events before sending a batch to Seq
`name`		The Bunyan stream name, which can be used when configuring Bunyan filters
`onError`	Log to console	A function to receive any errors raised when sending events to Seq
`reemitErrorEvents`	false	If `true`, error events raised by the stream will propagate as `'error'` events on the Bunyan logger object.
`serverUrl`	http://localhost:5341	The HTTP endpoint address of the Seq server

Message templates

You can specify property names as tokens in the log message to control how the event is rendered in Seq:

log.info({user: 'Alice'}, 'Hi, {user}!');

It is not necessary to specify tokens for all properties, but using this technique instead of string formatting will produce more easily machine-readable log events by associating the same template, and thus the same event id, with related events.

More Seq options for Node.js

pino-seq for the pino logging library