🪵 CloudWatch Custom Logger

A lightweight, dependency-free Node.js logger for AWS CloudWatch Logs, with optional batching, console output, and customizable metadata.

🚀 Installation

npm install "@alexandru.g/cloudwatch-custom-logger"

🧩 Usage Example

import { CloudWatchLogger } from '@alexandru.g/cloudwatch-custom-logger';

const logger = new CloudWatchLogger(
  {
    logGroupName: 'MyAppLogs',
    logStreamName: 'ServerStream',
    awsRegion: 'eu-central-1',
    awsAccessKeyId: process.env.AWS_KEY,
    awsSecretKey: process.env.AWS_SECRET,
  },
  { app: 'MyApp', environment: 'production' },
  true // enable console logging
);

await logger.init();

logger.info('Server started successfully');
logger.warn('API latency high', { latency: 180 });
logger.error('Database connection failed', { db: 'users-db' });

// Batch logs
logger.debug('User event queued', { userId: 42 }, true);
logger.debug('Another queued event', { userId: 99 }, true);

// Send all queued logs in one request
await logger.flush();

⚙️ Configuration

| Option | Type | Required | Description | | ---------------- | --------- | -------- | ----------------------------------------- | | logGroupName | string | ✅ | The CloudWatch log group name | | logStreamName | string | ✅ | The CloudWatch log stream name | | awsRegion | string | ✅ | AWS region (e.g. eu-west-1) | | awsAccessKeyId | string | ✅ | AWS access key | | awsSecretKey | string | ✅ | AWS secret key | | defaults | object | ❌ | Default metadata for all logs | | consoleLog | boolean | ❌ | Whether to also print logs to the console |

🧱 Methods

await logger.init()

Ensures the log stream exists. Creates it if necessary.

logger.log(level, message, meta = {}, batch = false)

Generic logging method. Use one of the convenience wrappers instead (info, warn, error, debug).

Parameters:

• level — one of "info" | "warn" | "error" | "debug"
• message — log message string
• meta — optional metadata object
• batch — if true, adds to an internal queue for later flushing

await logger.flush()

Sends all queued logs to CloudWatch in a single batch request.

logger.changeDefaults(newDefaults)

Replaces the default metadata for future logs.

Level-specific shortcuts

| Method | Description | | -------------------------------------- | -------------- | | logger.info(message, meta?, batch?) | Info-level log | | logger.warn(message, meta?, batch?) | Warning log | | logger.error(message, meta?, batch?) | Error log | | logger.debug(message, meta?, batch?) | Debug log |

🧠 Features

✅ Simple, clean API

✅ Supports batching with flush()

✅ Automatically creates log streams

✅ Includes console fallback logging

✅ TypeScript-friendly structure

🧪 Example Output

Each log is JSON-formatted and timestamped automatically:

{
  "level": "info",
  "message": "Server started successfully",
  "app": "MyApp",
  "environment": "production",
  "timestamp": 1739072381000
}

🪪 License

MIT © Alexandru Gurita