A small handler for AWS Cloudwatch

1.2.1 · active · verified Tue Apr 14

The `cloudwatch` library (by labrixdigital) provides a lightweight Python logging handler designed to send log events to AWS CloudWatch. It is particularly useful for applications running outside of AWS, on EC2 instances where AWS doesn't log automatically, or when custom log separation is desired. The current version is 1.2.1, with releases occurring infrequently, as its last update was in September 2023.

Warnings

breaking AWS CloudWatch is undergoing a protocol migration from AWS Query to more efficient AWS JSON 1.0 and Smithy RPC v2 CBOR protocols. While `cloudwatch` directly depends on `boto3`, older versions of `boto3` (pre-dating this change) might cause HTTP 500 errors with 'Missing Action' messages when interacting with CloudWatch. Users should ensure their `boto3` installation is up-to-date to avoid these issues.
Fix: Upgrade `boto3` to its latest version: `pip install --upgrade boto3`.
gotcha AWS CloudWatch Logs has a maximum event size limit of 256 KB. Sending messages larger than this limit can lead to errors. The `cloudwatch.CloudwatchHandler` provides an `overflow` parameter (defaulting to 'error') to manage this. Options include 'error' (raise exception), 'truncate' (cut message to size), or 'split' (divide into multiple parts).
Fix: Initialize `CloudwatchHandler` with `overflow='truncate'` or `overflow='split'` to automatically handle oversized messages, for example: `cloudwatch.CloudwatchHandler(..., overflow='truncate')`.
gotcha This library is designed for flexibility outside managed AWS logging environments. For serverless infrastructures like AWS Lambda or ECS, AWS often handles logging automatically. Using this custom handler in such environments might introduce unnecessary complexity or encounter limitations (e.g., related to asynchronous processes being frozen in Lambda), as AWS's native log handling is often more efficient and integrated.
Fix: For applications running on AWS Lambda or ECS, consider leveraging AWS's automatic logging to CloudWatch Logs where possible, or evaluate if a custom handler is truly necessary given the environment's characteristics.

Install

pip install cloudwatch Install with pip

Imports

CloudwatchHandler
```
from cloudwatch import cloudwatch; handler = cloudwatch.CloudwatchHandler(...)
```
The `cloudwatch` package itself contains the `cloudwatch` module from which `CloudwatchHandler` is imported.

Quickstart

This quickstart demonstrates how to integrate the `cloudwatch.CloudwatchHandler` with Python's standard `logging` module. It sets up a logger to send INFO, WARNING, and ERROR level messages to a specified AWS CloudWatch log group and stream. Ensure that `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables are set, or replace the placeholder strings with actual credentials for local testing. The `overflow` parameter is set to 'truncate' to handle messages larger than 256KB, preventing errors.

import logging
import os
from cloudwatch import cloudwatch

# Configure AWS credentials from environment variables
aws_access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID')
aws_secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY')
aws_region_name = os.environ.get('AWS_REGION', 'us-east-1') # e.g., 'us-east-1'

# Create a logger
logger = logging.getLogger('my_app_logger')
logger.setLevel(logging.INFO)

# Create a formatter
formatter = logging.Formatter('%(asctime)s : %(levelname)s - %(message)s')

# Create the CloudwatchHandler
# For log_group and log_stream, provide meaningful names for your application
try:
    handler = cloudwatch.CloudwatchHandler(
        log_group='my-application-logs',
        log_stream='instance-1',
        access_key_id=aws_access_key_id,
        secret_access_key=aws_secret_access_key,
        region_name=aws_region_name,
        overflow='truncate' # Options: 'error', 'truncate', 'split'
    )
    handler.setFormatter(formatter)
    logger.addHandler(handler)

    # Use the logger
    logger.info("Application started successfully.")
    logger.warning("A potential issue was detected.")
    logger.error("An error occurred during processing.")
    print("Logs sent to CloudWatch (check AWS console).")
except Exception as e:
    print(f"Failed to send logs to CloudWatch: {e}")
    print("Please ensure AWS credentials and region are correctly configured.")

view raw JSON →