cloudwatchlogger

Module to log directly to AWS CloudWatchLogs in NodeJS

cloudwatchlogger is a module that allows your Node.js app to send logs directly to AWS CloudWatchLogs.

• Creates LogGroups and LogStream if it doesnot exist
• Configurable batch size and retry options
• Provides a streaming interface
• CLI interface

Getting Started

Install the module with: npm install cloudwatchlogger --save

Install the module as a CLI tool npm install cloudwatchlogger -g

Usage

API

You can use the module by requiring and creating an instance of the logger by providing the AWS credentials and other options.

const Logger = require('cloudwatchlogger');

new Logger(OPTS).setupLogger('myGroupNameTest', 'myStreamNameTest',
        function(err, logger) {
            // logger is your actual logger instance
        }

Once you have the logger, you can call .log() function

    logger.log('Some Text'); // string
    logger.log(42); // number
    logger.log(true); // boolean
    logger.log({test:true}); // JSON

Logger OPTS

Logger OPTS allows you to pass in AWS credentials and few more options to control cloudwatchlogger behaviour.

OPTS needs to be a JSON like this:

{
    "accessKeyId": "XXXXX", // required
    "secretAccessKey": "YYYYY", // required
    "region": "us-west-2", // required
    "logLevel": "trace", // [optional] Use `Trace` if you want to see library logs
    "batchSize": 1024, // [optional] Messages are sent in batches of this size
    "batchDelay": 3000, // [optional] Delay before it sends if no messages are logged
    "maxRetries": 2 // [optional] Num of retries if posting to AWS fails
}

Full Example with Restify Server

'use strict'

const restify = require('restify');
const Logger = require('cloudwatchlogger');
let logger = null;
const server = restify.createServer({name: 'app'});
const opts = {
    "accessKeyId": "XXXXX", // required
    "secretAccessKey": "YYYYY", // required
    "region": "us-west-2", // required
    "logLevel": "trace", // [optional] Use `Trace` if you want to see library logs
    "batchSize": 1024, // [optional] Messages are sent in batches of this size
    "batchDelay": 3000, // [optional] Delay before it sends if no messages are logged
    "maxRetries": 2 // [optional] Num of retries if posting to AWS fails
};

/*
or, ask logger to read the AWS config from file json file
const opts = {
    "file":"./aws.config.json",
    "logLevel": "trace",
    "batchSize": 1024,
    "batchDelay": 3000,
    "maxRetries": 2
}
 */


server.pre( (req, res, next) => {
    req.id = 'RandomId123';
    // Example: Req object is circular with lots of other info
    // you would want to serialize it to a format that suits you
    logger.log({ method: req.method,
        url: req.url,
        id: req.id, // Example - assign and log a req id
        // later you can query in CloudWatchLogger with
        headers: req.headers,
        remoteAddress: req.connection.remoteAddress,
        remotePort: req.connection.remotePort });
    next();
});


server.get('/',  (req, res) => {
    logger.log('Some Text'); // string
    logger.log(42); // number
    logger.log(true); // boolean
    logger.log({test:true}); // JSON
    logger.log({
        statusCode: res.statusCode,
        id: req.id,
        header: res._header
    });
    res.send('hello world');
    next();
});


server.listen(3003, () => {
    // get an instance of logger and pass in the AWS CloudWatchLogs Group Name
    // and Stream Name
    // If GroupName or StreamName does not exists, library will create one for
    // you
    new Logger(opts).setupLogger('myGroupNameTest', 'myStreamNameTest',
        function(err, loggerInstance) {
            // you get back a loggerInstance when it establishes that log group
            // and log streams are valid
            logger = loggerInstance;
            console.log('Server listening on 3003 with CloudWatchLogger');
        });
});

CLI

cloudwatchlogger -h

  Usage: cloudwatchlogger [options]

  Options:

    -h, --help                               output usage information
    -V, --version                            output the version number
    -a, --accessKeyId <accessKeyId>          AWS Access Key Id
    -s, --secretAccessKey <secretAccessKey>  AWS Secret Access Key
    -r, --region <region>                    AWS Region
    -l, --logStreamName <logStreamName>      CloudWatch Log Stream Name
    -g, --logGroupName <logGroupName>        Cloud Watch Log Group Name
    -f, --file <pathToFile>                  or, Config JSON file containing AWS Credentials
    -d, --debug                              [optional] Enables debug logs for this library
    -m, --maxRetry <value>                   [optional] Max retries per log batch
    -b, --batchSize <value>                  [optional] Batch size

You can use cloudwatchlogger to stream output from one source into AWS CloudWatchLogs.

Example: The following will stream all the output from node server.js directly to AWS.

node server.js | cloudwatchlogger -f aws.config.json -g loggingGroup -l loggingStream

Contributing

Ensure that all linting and codestyle tasks are passing. Add unit tests for any new or changed functionality.

To start contributing, install the git prepush hooks:

make githooks

Before committing, lint and test your code using the included Makefile:

make prepush

If you have style errors, you can auto fix whitespace issues by running:

make codestyle-fix

License

Copyright (c) 2017 Rajat Kumar

Licensed under the MIT license.