winston-cloudwatch

What is winston-cloudwatch?

The winston-cloudwatch npm package is a transport for the popular logging library Winston that allows you to send logs to Amazon CloudWatch. This package is useful for integrating your application's logging with AWS CloudWatch, enabling centralized log management, monitoring, and analysis.

What are winston-cloudwatch's main functionalities?

Basic Logging to CloudWatch

This feature allows you to send basic log messages to AWS CloudWatch. By configuring the transport with your log group, log stream, and AWS region, you can start logging messages to CloudWatch.

const winston = require('winston');
const WinstonCloudWatch = require('winston-cloudwatch');

const logger = winston.createLogger({
  transports: [
    new WinstonCloudWatch({
      logGroupName: 'your-log-group',
      logStreamName: 'your-log-stream',
      awsRegion: 'your-region'
    })
  ]
});

logger.info('Hello, CloudWatch!');

Custom Log Format

This feature allows you to customize the format of your log messages before sending them to CloudWatch. In this example, the log messages are formatted with a timestamp and converted to JSON.

const winston = require('winston');
const WinstonCloudWatch = require('winston-cloudwatch');

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new WinstonCloudWatch({
      logGroupName: 'your-log-group',
      logStreamName: 'your-log-stream',
      awsRegion: 'your-region'
    })
  ]
});

logger.info('This is a custom formatted log message');

Error Logging

This feature demonstrates how to log error messages to CloudWatch. By catching an error and logging its message, you can keep track of exceptions and issues in your application.

const winston = require('winston');
const WinstonCloudWatch = require('winston-cloudwatch');

const logger = winston.createLogger({
  transports: [
    new WinstonCloudWatch({
      logGroupName: 'your-log-group',
      logStreamName: 'your-log-stream',
      awsRegion: 'your-region'
    })
  ]
});

try {
  throw new Error('Something went wrong!');
} catch (error) {
  logger.error(error.message);
}

Other packages similar to winston-cloudwatch

winston

Winston is a versatile logging library for Node.js that supports multiple transports. While it does not natively support CloudWatch, it can be extended with custom transports like winston-cloudwatch to achieve similar functionality.

bunyan

Bunyan is another logging library for Node.js that focuses on structured logging. It can be integrated with AWS CloudWatch using additional packages like 'bunyan-cloudwatch'. Compared to winston-cloudwatch, bunyan-cloudwatch offers similar functionality but is tailored for Bunyan's logging format.

log4js

Log4js is a logging library inspired by Apache Log4j. It supports various appenders, including one for AWS CloudWatch through the 'log4js-cloudwatch-appender' package. This provides similar capabilities to winston-cloudwatch but within the Log4js ecosystem.

README

winston-cloudwatch v6.3.0

:warning: WARNING
I realised I don't have time anymore to work on this. It's very likely no more updates will be made on this project.

Send logs to Amazon Cloudwatch using Winston

Starting from version 3.0.0 we moved aws-sdk into devDependencies to reduce the size of the package, so if you're not using this on AWS Lambda make sure you add aws-sdk dependency into your application package.json.

If you were using this library before version 2.0.0 have a look at the migration guide for Winston and at the updated examples.

• Features
• Installing
• Configuring
• Usage
• Options
• Examples
• Simulation

Features

• logging to AWS CloudWatchLogs
• logging to multiple streams
• programmatically flush logs and exit
• logging with multiple levels
• creates group / stream if they don't exist
• waits for an upload to suceed before trying the next
• truncates messages that are too big
• batches messages taking care of the AWS limit (you should use more streams if you hit this a lot)
• support for Winston's uncaught exception handler
• support for TypeScript, see TypeScript definition
• see options for more

Installing

$ npm install --save winston winston-cloudwatch @aws-sdk/client-cloudwatch-logs

Also consider that we have both winston and @aws-sdk/client-cloudwatch-logs configured as peerDependencies.

Configuring

AWS configuration works using ~/.aws/credentials as written in AWS JavaScript SDK guide.

As a best practice remember to use one stream per resource, so for example if you have 4 servers you should setup 4 streams on AWS CloudWatch Logs, this is a general best practice to avoid incurring in token clashes and to avoid limits of the service (see usage for more).

Credentials

Use awsOptions to set your credentials, like so:

new WinstonCloudWatch({
  ...,
  awsOptions: {
    credentials: {
      accessKeyId,
      secretAccessKey,
    },
    region,
  }
})

Region note

As specified in the docs:

The AWS SDK for Node.js doesn't select the region by default.

so you should take care of that. See the examples below.

If either the group or the stream do not exist they will be created for you.

AWS UI

For displaying time in AWS CloudWatch UI you should click on the gear in the top right corner in the page with your logs and enable checkbox "Creation Time".

TypeScript

Remember to install types for both winston and this library.

Usage

Please refer to AWS CloudWatch Logs documentation for possible contraints that might affect you. Also have a look at AWS CloudWatch Logs limits.

In ES5

var winston = require('winston'),
    WinstonCloudWatch = require('winston-cloudwatch');

In ES6

import { createLogger, format } from 'winston';
import * as WinstonCloudWatch from 'winston-cloudwatch';

export const log = createLogger({
  level: 'debug',
  format: format.json(),
  transports: [
    new WinstonCloudWatch({
      level: 'error',
      logGroupName: 'groupName',
      logStreamName: 'errors',
      awsRegion: 'eu-west-3'
      }),
  ]
});

You can also specify a function for the logGroupName and logStreamName options. This is handy if you are using this module in a server, say with express, as it enables you to easily split streams across dates, for example. There is an example of this here.

Logging to multiple streams

You could also log to multiple streams with / without different log levels, have a look at this example.

Consider that when using this feature you will have two instances of winston-cloudwatch, each with its own setInterval running.

Programmatically flush logs and exit

Think AWS Lambda for example, you don't want to leave the process running there for ever waiting for logs to arrive.

You could have winston-cloudwatch to flush and stop the setInterval loop (thus exiting), have a look at this example.

Custom AWS.CloudWatchLogs instance

const AWS = require('aws-sdk');

AWS.config.update({
  region: 'us-east-1',
});

winston.add(new WinstonCloudWatch({
  cloudWatchLogs: new AWS.CloudWatchLogs(),
  logGroupName: 'testing',
  logStreamName: 'first'
}));

Options

This is the list of options you could pass as argument to winston.add:

• name - string
• level - defaults to info
• logGroupName - string or function
• logStreamName - string or function
• cloudWatchLogs - AWS.CloudWatchLogs instance, used to set custom AWS instance.
• awsOptions - object, params as per docs, values in awsOptions are overridden by any other if specified, run this example to have a look; you should put your accessKeyId and secretAccessKey under a nexted credentials property, specify region under awsOptions
• jsonMessage - boolean, format the message as JSON
• messageFormatter - function, format the message the way you like. This function will receive a log object that has the following properties: level, message, and meta, which are passed by winston to the log function (see CustomLogger.prototype.log as an example)
• uploadRate - Number, how often logs have to be sent to AWS. Be careful of not hitting AWS CloudWatch Logs limits, the default is 2000ms.
• errorHandler - function, invoked with an error object, if not provided the error is sent to console.error
• retentionInDays - Number, defaults to 0, if set to one of the possible values 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653 the retention policy on the log group written will be set to the value provided.

AWS keys are usually picked by aws-sdk so you don't have to specify them, I provided the option just in case. Remember that awsRegion should still be set if you're using IAM roles.

Examples

Please refer to the provided examples for more hints.

Note that when running the examples the process will not exit because of the setInterval

Simulation

You could simulate how winston-cloudwatch runs by using the files in examples/simulate:

• running-process.js represents a winston-cloudwatch process that sits there, sends a couple logs then waits for a signal to send more
• log.sh is a script that you could run to send logs to the above

At this point you could for example run log.sh in a tight loop, like so

$ while true; do ./examples/simulate/log.sh $PID; sleep 0.2; done

and see what happens in the library, this might be useful to test if you need more streams for example, all you need to do is change running-process.js to better reflect your needs.

If you want more detailed information you could do

$ WINSTON_CLOUDWATCH_DEBUG=true node examples/simulate/running-process.js

which will print lots of debug statements as you might've guessed.

Changelog

6.3.0

Fix memory leaks in cloudwatch-integration.

https://github.com/lazywithclass/winston-cloudwatch/pull/214