@extk/logger-cloudwatch

Opinionated winston loggers with AWS CloudWatch support.

Install

npm install @extk/logger-cloudwatch

Loggers

getCloudwatchLogger(opts)

Streams JSON logs to AWS CloudWatch. Each process gets its own log stream named YYYY-MM-DD/pid-<pid>. Creates the log group if it doesn't exist.

import { getCloudwatchLogger } from '@extk/logger-cloudwatch';

const logger = getCloudwatchLogger({
    aws: {
        region: 'us-east-1',
        logGroup: '/my-app/production',
        credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        },
    },
});

logger.info('Request handled', { userId: 123 });

Optionally attach a context function to merge fields into every log entry:

const logger = getCloudwatchLogger({
    aws: { ... },
    contextFn: (info) => {
        info['service'] = 'payments';
        return info;
    },
});

| Option | Description | |-------------------|-------------| | aws.region | AWS region | | aws.logGroup | CloudWatch log group name | | aws.credentials | accessKeyId + secretAccessKey | | contextFn | Optional transform to add fields to every entry |

getConsoleLogger()

Logs to stdout. Intended for development or simple services.

import { getConsoleLogger } from '@extk/logger-cloudwatch';

const logger = getConsoleLogger();
logger.info('Server started');

getFileLogger(name?)

Writes to ./logs/<name>.log. Cached — calling with the same name returns the same instance.

import { getFileLogger } from '@extk/logger-cloudwatch';

const logger = getFileLogger('app');
logger.error(new Error('Something went wrong'));

| Option | Default | |--------|---------| | name | 'app' | | Output | ./logs/<name>.log | | Level | debug |

Log format

Console and file loggers use a human-readable format:

DD/MM/YYYY HH:mm:ss[LEVEL]: message
DD/MM/YYYY HH:mm:ss[ERROR]: Error: something\n    at ...  ← stack trace for errors

CloudWatch receives structured JSON with timestamp, level, message, and any extra fields.