Registry / aws / aws-logging-handlers

aws-logging-handlers

JSON →
library2.0.5pypypi✓ verified 85d ago

AWS Logging Handlers is a Python library that provides multithreaded logging handlers for streaming log records to Amazon S3 and Kinesis Data Streams. It leverages asynchronous uploading with multiple worker threads and supports gzip compression for S3 logs. The library is actively maintained, with version 2.0.5 currently available, and receives regular minor updates for improvements and bug fixes.

pip install aws-logging-handlers
INSTALL
IMPORT
SIG · AWS-LOGGING-HANDLE
A
aws-logging-handlers
awspythonv2.0.5
Install
4.6s avg
Import
690ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.5 · 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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.722s · 52.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 4.6s · import 0.658s · 53MB
50MB installed
● package 50MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

S3Handler
from aws_logging_handlers.S3 import S3Handler
from aws_logging_handlers.s3 import S3Handler
Module names for handlers were refactored in version 2.x; ensure 'S3' is capitalized.
KinesisHandler
from aws_logging_handlers.Kinesis import KinesisHandler
from aws_logging_handlers.kinesis import KinesisHandler
Module names for handlers were refactored in version 2.x; ensure 'Kinesis' is capitalized.

This quickstart demonstrates how to configure both `S3Handler` and `KinesisHandler` to stream log records to their respective AWS services. It shows how to set a formatter, add handlers to a logger, and crucially, how to call `logging.shutdown()` for graceful termination and log flushing. Ensure AWS credentials (e.g., via environment variables or IAM roles) and the specified S3 bucket and Kinesis stream exist and are correctly configured.

import logging import os from aws_logging_handlers.S3 import S3Handler from aws_logging_handlers.Kinesis import KinesisHandler # Configure AWS credentials (replace with your actual bucket and stream names) bucket_name = os.environ.get('AWS_S3_LOG_BUCKET', 'your-s3-log-bucket') kinesis_stream_name = os.environ.get('AWS_KINESIS_LOG_STREAM', 'your-kinesis-log-stream') aws_region = os.environ.get('AWS_REGION', 'us-east-1') # Configure S3 handler (logs rotate every 5MB or 120 seconds) s3_handler = S3Handler( log_group='test_log_s3', bucket_name=bucket_name, workers=3, # Number of upload worker threads session_kwargs={'region_name': aws_region} ) # Configure Kinesis handler kinesis_handler = KinesisHandler( log_group='test_log_kinesis', stream_name=kinesis_stream_name, workers=1, # Number of upload worker threads session_kwargs={'region_name': aws_region} ) # Set up formatter formatter = logging.Formatter( '[%(asctime)s] %(filename)s:%(lineno)d} %(levelname)s - %(message)s' ) s3_handler.setFormatter(formatter) kinesis_handler.setFormatter(formatter) # Get logger and add handlers logger = logging.getLogger('my_app') logger.setLevel(logging.INFO) logger.addHandler(s3_handler) logger.addHandler(kinesis_handler) # Log some messages logger.info("This is an info message to S3 and Kinesis.") logger.warning("A warning occurred in the application.") logger.error("An error message that should go to AWS services.") # Ensure all buffered logs are flushed and workers shut down gracefully logging.shutdown()
Debug
Known issues
breakingMajor architectural and directory tree refactoring in version 2.0.1 introduced breaking changes, particularly in import paths and potentially handler instantiation. Code written for 0.x versions will likely require updates.
fix
Update import statements to use capitalized submodule names (e.g., `from aws_logging_handlers.S3 import S3Handler` instead of `from aws_logging_handlers.s3 import S3Handler`). Review the latest documentation for handler constructor arguments.
affects: 0.x to 2.x
gotchaFailure to call `logging.shutdown()` can result in lost log messages, especially in short-lived applications (like AWS Lambda functions or scripts). The library uses worker threads for asynchronous uploads, and these threads need a signal to flush remaining buffers before the application exits.
fix
Always call `logging.shutdown()` at the end of your application's lifecycle to ensure all buffered logs are flushed to S3 or Kinesis and worker threads terminate gracefully.
affects: All
gotchaThe S3 bucket and Kinesis stream specified in the handler configuration must already exist and have appropriate IAM permissions for the AWS credentials being used. The library does not create these resources.
fix
Ensure the target S3 bucket and Kinesis stream are pre-provisioned in AWS. Verify that the IAM user/role associated with your application has `s3:PutObject`, `kinesis:PutRecord`, and `kinesis:PutRecords` permissions (among others as needed for specific configurations) for the target resources.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_logging_handlers.s3'
This error typically occurs when upgrading from `aws-logging-handlers` version 0.x to 2.x. The module structure was refactored, changing `s3` (lowercase) to `S3` (capitalized).
fix
Update your import statements: change `from aws_logging_handlers.s3 import S3Handler` to `from aws_logging_handlers.S3 import S3Handler`. Apply similar changes for `KinesisHandler`.
botocore.exceptions.ClientError: An error occurred (ExpiredToken) when calling the PutObject operation: The provided token has expired.
The AWS credentials configured for the Boto3 session (either via environment variables, shared credentials file, or IAM role) are invalid, expired, or lack the necessary permissions to perform the logging operation.
fix
Verify your AWS credentials and IAM permissions. Ensure environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` are correctly set and not expired. If using an IAM role, confirm it has policies allowing `s3:PutObject` for the target S3 bucket and `kinesis:PutRecord`/`kinesis:PutRecords` for the target Kinesis stream.
Logs are not appearing in the configured S3 bucket or Kinesis stream, or are significantly delayed.
This can happen due to several reasons: `logging.shutdown()` not being called (leading to un-flushed buffers), insufficient worker threads for high log volume, network connectivity issues to AWS, or incorrect configuration of bucket/stream names or regions.
fix
1. Ensure `logging.shutdown()` is called at the application's exit. 2. Increase the `workers` parameter for `S3Handler` or `KinesisHandler` if dealing with high log volumes. 3. Check network connectivity to AWS. 4. Double-check that `bucket_name`, `stream_name`, and `session_kwargs={'region_name': ...}` are accurate and match your AWS setup.
Upgrade
Version history
2.0.5latest on PyPI · released Nov 30, 2020
Audit
Dependencies
boto3requiredRequired for interacting with AWS S3 and Kinesis services for logging. The library relies on boto3 for asynchronous multipart uploading and AWS API calls.
Agent activity
33 hits · last 30 days
node
26
Amazon
1
OpenAI (training)
1
Resources
aws-logging-handlers — pip install aws-logging-handlers · libregistry