winston-cloudwatch v1.6.0

Send logs to Amazon Cloudwatch using Winston.

Features
Installing
Configuring
Usage
Options
Examples

Features

logging to AWS CloudWatchLogs
logging to multiple streams
logging with multiple levels
creates group / stream if they don't exist
doesn't try to buffer your unsent logs (you should use more streams)
waits for an upload to suceed before trying the next
truncates messages that are too big
batches messages taking care of the AWS limit
support for Winston's uncaught exception handler
see options for more

Installing

$ npm install --save winston winston-cloudwatch

Configuring

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

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.

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".

Usage

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

var winston = require('winston'),
    WinstonCloudWatch = require('../index');

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

winston.error('1');

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

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.

Options

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

level - defaults to info
logGroupName
logStreamName
awsAccessKeyId
awsSecretKey
awsRegion
awsOptions - object, params as per docs, values in awsOptions are overridden by any other if specified, run this example to have a look
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, msg, and meta, which are passed by winston to the log function (see CustomLogger.prototype.log as an example)
proxyServer - String, use proxyServer as proxy in httpOptions
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

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

rebolyte / winston-cloudwatch