Install & Compatibility
Where this runs
tested against v1.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 50.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.000s · 51MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CloudwatchHandler
✓ import cloudwatch
✗ from cloudwatch import CloudwatchHandler
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.")
Debug
Known issues
breakingAWS 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.fixUpgrade `boto3` to its latest version: `pip install --upgrade boto3`.
affects: Dependent on `boto3` versions that predate AWS CloudWatch protocol updates.
gotchaAWS 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).fixInitialize `CloudwatchHandler` with `overflow='truncate'` or `overflow='split'` to automatically handle oversized messages, for example: `cloudwatch.CloudwatchHandler(..., overflow='truncate')`.
affects: All versions
gotchaThis 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.fixFor 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.
affects: All versions
Upgrade
Version history
1.2.1latest on PyPI · released Sep 1, 2023
Audit
Dependencies
boto3requiredRequired for interacting with AWS CloudWatch Logs API.