log4js appender - AWS CloudWatch

Note that this project is a fork of the below description. It has been updated to resolve importing into older projects. Everything below this line is taken from the original forked project.

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

Installation

npm registry

1npm install log4js-appender-cloudwatch

Configuration

Roles

Required

1logs:PutLogEvents

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

1logs:PutLogEvents
2logs:CreateLogGroup
3logs:CreateLogStream
4logs:DescribeLogStreams
5logs:DescribeLogGroups

Reqired for testing.

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

1logs:PutLogEvents
2logs:GetLogEvents

1{
2	"Version": "2012-10-17",
3	"Statement": [
4		{
5			"Action": [
6				"logs:PutLogEvents",
7				"logs:GetLogEvents"
8			],
9			"Effect": "Allow",
10			"Resource": "*"
11		}
12	]
13}

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.

1import "log4js-appender-cloudwatch";

Example

1import log4js from "log4js";
2
3import "log4js-appender-cloudwatch";
4
5log4js.configure({
6	appenders: {
7		cloudwatch: {
8			type: "log4js-appender-cloudwatch",
9			accessKeyId: "<secret>",
10			secretAccessKey: "<secret>",
11			region: "<config>",
12			logGroupName: "<config>",
13			logStreamName: "<config>",
14			batchSize: 10,
15			bufferTimeout: 1000, // in ms
16		},
17	},
18	categories: {
19		default: {
20			level: "debug",
21			appenders: [
22				"cloudwatch",
23			],
24		},
25	},
26});
27
28const log = log4js.getLogger();
29// ...

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.

1# .env
2ACCESSKEY_ID="<key>"
3SECRET_ACCESS_KEY="<key>"

Then, you're ready to run tests:

1npm test