CloudWatch Sink Issues

Common problems when sending logs to AWS CloudWatch Logs.

InvalidSequenceTokenException

  • Cause: Multiple writers to the same stream or stale sequence token.

  • Fix: The sink retries automatically using expectedSequenceToken. Ensure each instance uses a unique log_stream_name (e.g., include hostname) to avoid contention.

ThrottlingException

  • Cause: CloudWatch throttling during bursts.

  • Fix: Lower batch_size, increase batch_timeout_seconds, or reduce log volume. The sink backs off exponentially by default.

ResourceNotFoundException

  • Cause: Log group or stream is missing.

  • Fix: Keep create_log_group/create_log_stream enabled, or pre-create resources. Verify IAM permissions (logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogStreams).

Oversized events (256 KB)

  • Cause: Single log entry exceeds CloudWatch event limit.

  • Fix: Enable size_guard with max_bytes=256000 to truncate or drop before reaching the sink.

Local testing

  • Use LocalStack: set FAPILOG_CLOUDWATCH__ENDPOINT_URL=http://localhost:4566 and credentials (test/test).

  • See tests/integration/test_cloudwatch_sink_localstack.py and examples/cloudwatch_logging.