log4js appender - AWS CloudWatch

This module provides a custom appender for log4js that sends logs to AWS CloudWatch using the AWS v3 SDK.

Installation

npm registry

npm install log4js-appender-cloudwatch

Configuration

Roles

Required

logs:PutLogEvents

To enable the appender to create a group and log stream in AWS, adition roleare required.

logs:PutLogEvents
logs:CreateLogGroup
logs:CreateLogStream
logs:DescribeLogStreams
logs:DescribeLogGroups

Reqired for testing.

To run tests, create .env with AWS access and secret keys.

logs:PutLogEvents
logs:GetLogEvents

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "logs:PutLogEvents",
                "logs:GetLogEvents"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

TypeScript

If you're using TypeScript, importing this library as a side effect will automatically merge the log4js interface Appenders. This merging enables autocomplete for the appenders configuration, providing convenient access to its properties.

import "log4js-appender-cloudwatch";

Example

import log4js from "log4js";

import "log4js-appender-cloudwatch";

log4js.configure({
    appenders: {
        cloudwatch: {
            type: "log4js-appender-cloudwatch",
            accessKeyId: "<secret>",
            secretAccessKey: "<secret>",
            region: "<config>",
            logGroupName: "<config>",
            logStreamName: "<config>",
            batchSize: 10,
            bufferTimeout: 1000, // in ms
        },
    },
    categories: {
        default: {
            level: "debug",
            appenders: [
                "cloudwatch",
            ],
        },
    },
});

const log = log4js.getLogger();
// ...

Options

type

Required\ Type: log4js-appender-cloudwatch

Type of appender that's loaded from node_modules.

batchSize

Required\ Type: number

Maximum number of log events to include in a single batch when sending. Once the batch size is reached, it will be sent to CloudWatch.

bufferTimeout

Required\ Type: number

Maximum time (in milliseconds) to wait before sending a batch of logs, regardless of the batch size. If the timeout is reached before the batch size is met, the logs will be sent.

logGroupName (aws)

Required\ Type: string

The name of the log group in AWS CloudWatch Logs where your logs are stored.

logStreamName (aws)

Required\ Type: string

The name of the log stream within the specified log group where your logs are stored.

region (aws)

Required\ Type: string

The AWS region where your log group and log stream are located.

accessKeyId (aws)

Required\ Type: string

Your AWS access key ID for authentication.

secretAccessKey (aws)

Required\ Type: string

Your AWS secret access key for authentication.

sessionToken (aws)

Optional\ Type: string

Your AWS session token for authentication. This is used when you are using temporary security credentials.

Testing

To test this library during development, you'll need to provide your AWS credentials. These credentials should be stored securely in a .env file located at the root of your project directory.

# .env
ACCESSKEY_ID="<key>"
SECRET_ACCESS_KEY="<key>"

Then, you're ready to run tests:

npm test