# cloudwatchlogger

> Module to log directly to AWS CloudWatchLogs in NodeJS

Latest version **1.0.4** (published 2017-04-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install cloudwatchlogger
pnpm add cloudwatchlogger
yarn add cloudwatchlogger
bun add cloudwatchlogger
```

Provides the command `cloudwatchlogger`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2017-04-20 |
| First published | 2017-04-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rajat Kumar |
| Maintainers | rajatkumar |
| Keywords | cloudwatchlogger, AWS,  CloudWatchLogs,  AWS SDK,  Streaming,  logging |

## Links

- npm: https://www.npmjs.com/package/cloudwatchlogger
- Repository: https://github.com/rajatkumar/cloudwatchlogger
- Issues: https://github.com/rajatkumar/cloudwatchlogger/issues
- npm.io page: https://npm.io/package/cloudwatchlogger

## Dependencies (7)

- [pino](https://npm.io/package/pino.md) ^4.2.4
- [pump](https://npm.io/package/pump.md) ^1.0.2
- [split2](https://npm.io/package/split2.md) ^2.1.1
- [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.41.0
- [through2](https://npm.io/package/through2.md) ^2.0.3
- [commander](https://npm.io/package/commander.md) ^2.9.0
- [better-queue](https://npm.io/package/better-queue.md) ^3.8.5

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 1.0.4 (latest) — 2017-04-20
- 1.0.3 — 2017-04-20
- 1.0.2 — 2017-04-19
- 1.0.1 — 2017-04-19
- 1.0.0 — 2017-04-19
- 0.1.0 — 2017-04-18

## README

# cloudwatchlogger

[![NPM Version](https://img.shields.io/npm/v/cloudwatchlogger.svg)](https://npmjs.org/package/cloudwatchlogger)
[![Build Status](https://travis-ci.org/rajatkumar/cloudwatchlogger.svg?branch=master)](https://travis-ci.org/rajatkumar/cloudwatchlogger)
[![Coverage Status](https://coveralls.io/repos/github/rajatkumar/cloudwatchlogger/badge.svg?branch=master)](https://coveralls.io/github/rajatkumar/cloudwatchlogger?branch=master)
[![Dependency Status](https://david-dm.org/rajatkumar/cloudwatchlogger.svg)](https://david-dm.org/rajatkumar/cloudwatchlogger)
[![devDependency Status](https://david-dm.org/rajatkumar/cloudwatchlogger/dev-status.svg)](https://david-dm.org/rajatkumar/cloudwatchlogger#info=devDependencies)
[![bitHound Score](https://www.bithound.io/github/rajatkumar/cloudwatchlogger/badges/score.svg)](https://www.bithound.io/github/rajatkumar/cloudwatchlogger/master)
[![nsp status](https://img.shields.io/badge/NSP%20status-no%20vulnerabilities-green.svg)](https://travis-ci.org/rajatkumar/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.

```js
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


```js

    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:

```js
{
    "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

```js


'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:

```sh
make githooks
```

Before committing, lint and test your code using the included Makefile:
```sh
make prepush
```

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

```sh
make codestyle-fix
```

## License

Copyright (c) 2017 Rajat Kumar

Licensed under the MIT license.

---
_Source: https://npm.io/package/cloudwatchlogger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
