@logtape/cloudwatch-logs 1.0.0-dev.211

package/sink.test.ts

@@ -0,0 +1,331 @@
+import { suite } from "@alinea/suite";
+import {
+  CloudWatchLogsClient,
+  PutLogEventsCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+import type { LogRecord } from "@logtape/logtape";
+import { jsonLinesFormatter } from "@logtape/logtape";
+import { assertEquals, assertInstanceOf } from "@std/assert";
+import { mockClient } from "aws-sdk-client-mock";
+import { getCloudWatchLogsSink } from "./sink.ts";
+
+const test = suite(import.meta);
+
+const mockLogRecord: LogRecord = {
+  category: ["test"],
+  level: "info",
+  message: ["Hello, ", "world", "!"],
+  rawMessage: "Hello, {name}!",
+  timestamp: Date.now(),
+  properties: {},
+};
+
+test("getCloudWatchLogsSink() creates a working sink", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    region: "us-east-1",
+    batchSize: 1,
+    flushInterval: 0,
+  });
+
+  sink(mockLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+  const call = cwlMock.commandCalls(PutLogEventsCommand)[0];
+  assertEquals(call.args[0].input.logGroupName, "/test/log-group");
+  assertEquals(call.args[0].input.logStreamName, "test-stream");
+  assertEquals(call.args[0].input.logEvents?.length, 1);
+  assertEquals(call.args[0].input.logEvents?.[0].message, 'Hello, "world"!');
+});
+
+test("getCloudWatchLogsSink() batches multiple log events", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 3,
+    flushInterval: 0,
+  });
+
+  sink(mockLogRecord);
+  sink(mockLogRecord);
+  sink(mockLogRecord);
+
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+  const call = cwlMock.commandCalls(PutLogEventsCommand)[0];
+  assertEquals(call.args[0].input.logEvents?.length, 3);
+});
+
+test("getCloudWatchLogsSink() flushes when batch size is reached", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 2,
+    flushInterval: 0,
+  });
+
+  sink(mockLogRecord);
+  sink(mockLogRecord); // Should flush here
+  sink(mockLogRecord); // Should be in next batch
+
+  await sink[Symbol.asyncDispose](); // Should flush remaining
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 2);
+  assertEquals(
+    cwlMock.commandCalls(PutLogEventsCommand)[0].args[0].input.logEvents
+      ?.length,
+    2,
+  );
+  assertEquals(
+    cwlMock.commandCalls(PutLogEventsCommand)[1].args[0].input.logEvents
+      ?.length,
+    1,
+  );
+});
+
+test("getCloudWatchLogsSink() with custom client", async () => {
+  const client = new CloudWatchLogsClient({ region: "us-west-2" });
+  const cwlMock = mockClient(client);
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    client,
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 1,
+    flushInterval: 0,
+  });
+
+  sink(mockLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+});
+
+test("getCloudWatchLogsSink() handles credentials", () => {
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    region: "eu-west-1",
+    credentials: {
+      accessKeyId: "test-key",
+      secretAccessKey: "test-secret",
+    },
+  });
+
+  assertInstanceOf(sink, Function);
+  assertInstanceOf(sink[Symbol.asyncDispose], Function);
+});
+
+test("getCloudWatchLogsSink() handles errors gracefully", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).rejects(new Error("Permanent failure"));
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 1,
+    flushInterval: 0,
+    maxRetries: 0, // No retries
+    retryDelay: 10,
+  });
+
+  sink(mockLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  // Should attempt once and fail gracefully
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+});
+
+test("getCloudWatchLogsSink() handles large message batches", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  // Create a message that will exceed 1MB when combined with overhead
+  const largeMessage = "x".repeat(600000); // ~600KB message
+  const largeLogRecord: LogRecord = {
+    category: ["test"],
+    level: "info",
+    message: [largeMessage],
+    rawMessage: largeMessage,
+    timestamp: Date.now(),
+    properties: {},
+  };
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 10,
+    flushInterval: 0,
+  });
+
+  // Add two large messages - should exceed 1MB limit
+  sink(largeLogRecord);
+  sink(largeLogRecord);
+
+  await sink[Symbol.asyncDispose]();
+
+  const calls = cwlMock.commandCalls(PutLogEventsCommand);
+  // Should either flush immediately due to size or flush remaining on dispose
+  assertEquals(calls.length >= 1, true);
+});
+
+test("getCloudWatchLogsSink() formats complex log messages", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const complexLogRecord: LogRecord = {
+    category: ["app", "module"],
+    level: "error",
+    message: ["User ", { id: 123, name: "John" }, " failed to login"],
+    rawMessage: "User {user} failed to login",
+    timestamp: Date.now(),
+    properties: { error: "Invalid password" },
+  };
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 1,
+    flushInterval: 0,
+  });
+
+  sink(complexLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  const call = cwlMock.commandCalls(PutLogEventsCommand)[0];
+  assertEquals(
+    call.args[0].input.logEvents?.[0].message,
+    'User {"id":123,"name":"John"} failed to login',
+  );
+});
+
+test("getCloudWatchLogsSink() respects batch size limits", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 50000, // Should be clamped to 10000
+    flushInterval: 0,
+  });
+
+  // Verify the sink works (batch size should be internally limited)
+  sink(mockLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+});
+
+test("getCloudWatchLogsSink() flushes remaining events on disposal", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 10,
+    flushInterval: 0,
+  });
+
+  sink(mockLogRecord);
+  sink(mockLogRecord);
+
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+  assertEquals(
+    cwlMock.commandCalls(PutLogEventsCommand)[0].args[0].input.logEvents
+      ?.length,
+    2,
+  );
+});
+
+test("getCloudWatchLogsSink() supports JSON Lines formatter", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 1,
+    flushInterval: 0,
+    formatter: jsonLinesFormatter,
+  });
+
+  const structuredLogRecord: LogRecord = {
+    category: ["app", "database"],
+    level: "error",
+    message: ["User ", { id: 123, name: "John" }, " failed to connect"],
+    rawMessage: "User {user} failed to connect",
+    timestamp: 1672531200000, // Fixed timestamp for testing
+    properties: { error: "Connection timeout", retries: 3 },
+  };
+
+  sink(structuredLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+  const call = cwlMock.commandCalls(PutLogEventsCommand)[0];
+  const logMessage = call.args[0].input.logEvents?.[0].message;
+
+  // Parse the JSON message to verify structure
+  const parsedMessage = JSON.parse(logMessage!);
+
+  // Check what fields are actually present in jsonLinesFormatter output
+  assertEquals(parsedMessage["@timestamp"], "2023-01-01T00:00:00.000Z");
+  assertEquals(parsedMessage.level, "ERROR"); // jsonLinesFormatter uses uppercase
+  assertEquals(parsedMessage.logger, "app.database"); // category becomes logger
+  assertEquals(
+    parsedMessage.message,
+    'User {"id":123,"name":"John"} failed to connect',
+  ); // pre-formatted message
+  assertEquals(parsedMessage.properties.error, "Connection timeout");
+  assertEquals(parsedMessage.properties.retries, 3);
+});
+
+test("getCloudWatchLogsSink() uses default text formatter when no formatter provided", async () => {
+  const cwlMock = mockClient(CloudWatchLogsClient);
+  cwlMock.reset();
+  cwlMock.on(PutLogEventsCommand).resolves({});
+
+  const sink = getCloudWatchLogsSink({
+    logGroupName: "/test/log-group",
+    logStreamName: "test-stream",
+    batchSize: 1,
+    flushInterval: 0,
+    // No formatter specified - should use default
+  });
+
+  sink(mockLogRecord);
+  await sink[Symbol.asyncDispose]();
+
+  assertEquals(cwlMock.commandCalls(PutLogEventsCommand).length, 1);
+  const call = cwlMock.commandCalls(PutLogEventsCommand)[0];
+  const logMessage = call.args[0].input.logEvents?.[0].message;
+
+  // Should be plain text, not JSON
+  assertEquals(logMessage, 'Hello, "world"!');
+});

package/sink.ts

@@ -0,0 +1,140 @@
+import {
+  CloudWatchLogsClient,
+  type InputLogEvent,
+  PutLogEventsCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+import type { LogRecord, Sink, TextFormatter } from "@logtape/logtape";
+import type { CloudWatchLogsSinkOptions } from "./types.ts";
+
+/**
+ * Gets a CloudWatch Logs sink that sends log records to AWS CloudWatch Logs.
+ *
+ * @param options Configuration options for the CloudWatch Logs sink.
+ * @returns A sink that sends log records to CloudWatch Logs.
+ * @since 1.0.0
+ */
+export function getCloudWatchLogsSink(
+  options: CloudWatchLogsSinkOptions,
+): Sink & AsyncDisposable {
+  const client = options.client ??
+    new CloudWatchLogsClient({
+      region: options.region ?? "us-east-1",
+      credentials: options.credentials,
+    });
+
+  const batchSize = Math.min(Math.max(options.batchSize ?? 1000, 1), 10000);
+  const flushInterval = options.flushInterval ?? 1000;
+  const maxRetries = Math.max(options.maxRetries ?? 3, 0);
+  const retryDelay = Math.max(options.retryDelay ?? 100, 0);
+
+  // Default formatter that formats message parts into a simple string
+  const defaultFormatter: TextFormatter = (record) => {
+    let result = "";
+    for (let i = 0; i < record.message.length; i++) {
+      if (i % 2 === 0) {
+        result += record.message[i];
+      } else {
+        result += JSON.stringify(record.message[i]);
+      }
+    }
+    return result;
+  };
+
+  const formatter = options.formatter ?? defaultFormatter;
+
+  const logEvents: InputLogEvent[] = [];
+  let currentBatchSize = 0;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+
+  const OVERHEAD_PER_EVENT = 26; // AWS overhead per log event
+  const MAX_BATCH_SIZE_BYTES = 1048576; // 1 MiB
+
+  function scheduleFlush(): void {
+    if (flushInterval <= 0 || flushTimer !== null) return;
+
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      if (logEvents.length > 0) {
+        void flushEvents();
+      }
+    }, flushInterval);
+  }
+
+  async function flushEvents(): Promise<void> {
+    if (logEvents.length === 0 || disposed) return;
+
+    const events = logEvents.splice(0);
+    currentBatchSize = 0;
+
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+
+    await sendEventsWithRetry(events, maxRetries);
+  }
+
+  async function sendEventsWithRetry(
+    events: InputLogEvent[],
+    remainingRetries: number,
+  ): Promise<void> {
+    try {
+      const command = new PutLogEventsCommand({
+        logGroupName: options.logGroupName,
+        logStreamName: options.logStreamName,
+        logEvents: events,
+      });
+
+      await client.send(command);
+    } catch (error) {
+      if (remainingRetries > 0) {
+        const delay = retryDelay * Math.pow(2, maxRetries - remainingRetries);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        await sendEventsWithRetry(events, remainingRetries - 1);
+      } else {
+        console.error("Failed to send log events to CloudWatch Logs:", error);
+      }
+    }
+  }
+
+  function formatLogMessage(record: LogRecord): string {
+    return formatter(record);
+  }
+
+  const sink: Sink & AsyncDisposable = (record: LogRecord) => {
+    if (disposed) return;
+
+    const message = formatLogMessage(record);
+    const messageBytes = new TextEncoder().encode(message).length;
+    const eventSize = messageBytes + OVERHEAD_PER_EVENT;
+
+    const logEvent: InputLogEvent = {
+      timestamp: record.timestamp,
+      message,
+    };
+
+    logEvents.push(logEvent);
+    currentBatchSize += eventSize;
+
+    const shouldFlushBySize = currentBatchSize > MAX_BATCH_SIZE_BYTES;
+    const shouldFlushByCount = logEvents.length >= batchSize;
+
+    if (shouldFlushBySize || shouldFlushByCount) {
+      void flushEvents();
+    } else {
+      scheduleFlush();
+    }
+  };
+
+  sink[Symbol.asyncDispose] = async () => {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    await flushEvents();
+    disposed = true;
+  };
+
+  return sink;
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["mod.ts"],
+  dts: {
+    sourcemap: true,
+  },
+  format: ["esm", "cjs"],
+  platform: "neutral",
+  unbundle: true,
+});

package/types.ts

@@ -0,0 +1,78 @@
+import type { CloudWatchLogsClient } from "@aws-sdk/client-cloudwatch-logs";
+import type { TextFormatter } from "@logtape/logtape";
+
+/**
+ * Options for configuring the CloudWatch Logs sink.
+ * @since 1.0.0
+ */
+export interface CloudWatchLogsSinkOptions {
+  /**
+   * An existing CloudWatch Logs client instance.
+   * If provided, the client will be used directly and other connection
+   * options (region, credentials) will be ignored.
+   */
+  readonly client?: CloudWatchLogsClient;
+
+  /**
+   * The name of the log group to send log events to.
+   */
+  readonly logGroupName: string;
+
+  /**
+   * The name of the log stream within the log group.
+   */
+  readonly logStreamName: string;
+
+  /**
+   * The AWS region to use when creating a new client.
+   * Ignored if `client` is provided.
+   * @default "us-east-1"
+   */
+  readonly region?: string;
+
+  /**
+   * AWS credentials to use when creating a new client.
+   * Ignored if `client` is provided.
+   * If not provided, the AWS SDK will use default credential resolution.
+   */
+  readonly credentials?: {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+  };
+
+  /**
+   * Maximum number of log events to batch before sending to CloudWatch.
+   * Must be between 1 and 10,000.
+   * @default 1000
+   */
+  readonly batchSize?: number;
+
+  /**
+   * Maximum time in milliseconds to wait before flushing buffered log events.
+   * Set to 0 or negative to disable time-based flushing.
+   * @default 1000
+   */
+  readonly flushInterval?: number;
+
+  /**
+   * Maximum number of retry attempts for failed requests.
+   * @default 3
+   */
+  readonly maxRetries?: number;
+
+  /**
+   * Initial delay in milliseconds for exponential backoff retry strategy.
+   * @default 100
+   */
+  readonly retryDelay?: number;
+
+  /**
+   * Text formatter to use for formatting log records before sending to CloudWatch Logs.
+   * If not provided, defaults to a simple text formatter.
+   * Use `jsonLinesFormatter()` from "@logtape/logtape" for JSON structured logging
+   * to enable powerful CloudWatch Logs Insights querying capabilities.
+   * @since 1.0.0
+   */
+  readonly formatter?: TextFormatter;
+}