SmooAI is an AI-powered platform for helping businesses multiply their customer, employee, and developer experience.
Learn more on smoo.ai
Check out other SmooAI packages at smoo.ai/open-source
The missing piece for AWS & Browser logging - A contextual logging system that automatically captures the full execution context you need to debug production issues, without the manual setup.
This is the Python port of @smooai/logger, mirroring the TypeScript API for backend services. It provides the same contextual logging capabilities with automatic AWS context capture and correlation tracking.
Ever spent hours debugging an AWS service in production, only to realize you're missing critical context? Traditional loggers give you the message, but not the story.
smooai-logger automatically captures:
For AWS Services:
- 📍 Exact code location - File, line number, and call stack for every log
- 🔗 Request journey - Correlation IDs that follow requests across services
- ⚡ AWS context - Service-specific metadata and execution details
- 🌐 HTTP details - Headers, methods, status codes from API Gateway
- 📬 Message context - SQS attributes, EventBridge events, SNS messages
- 🔧 Service integration - Lambda, ECS, Fargate, EC2, and more
pip install smooai-loggeror with uv:
uv add smooai-loggerEvery log entry includes the exact location in your code:
fromsmooai_loggerimportAwsServerLoggerlogger=AwsServerLogger()
logger.info("User created")
# Output includes:
{
"callerContext": {
"stack": [
"at UserService.create_user (/src/services/user_service.py:42:16)",
"at process_request (/src/handlers/user_handler.py:15:23)",
"at handler (/src/index.py:8:10)"
]
}
}No more guessing which function logged what - the full execution path is right there.
Correlation IDs automatically flow through your entire system:
# Service A: API Gateway Handlerlogger.add_lambda_context(event, context)
logger.info("Request received") # Correlation ID: abc-123# Service B: SQS Processor (automatically extracts ID)logger.add_sqs_record_context(record)
logger.info("Processing message") # Same Correlation ID: abc-123# Service C: Another Lambda (receives via HTTP header)logger.info("Completing workflow") # Still Correlation ID: abc-123fromsmooai_loggerimportAwsServerLogger, Levellogger=AwsServerLogger(name="UserAPI")
defhandler(event, context):
logger.add_lambda_context(event, context)
try:
user=create_user(event["body"])
logger.info("User created successfully", {"userId": user.id})
return {"statusCode": 201, "body": json.dumps(user)}
exceptExceptionaserror:
logger.error("Failed to create user", error, {
"body": event["body"],
"headers": event["headers"],
})
raiseerrorimportosfromsmooai_loggerimportAwsServerLogger, Levellogger=AwsServerLogger(
name="OrderService",
level=Level.INFO,
)
# Automatically captures container metadata@app.post('/orders')asyncdefcreate_order(request):
logger.add_context({
"taskArn": os.environ.get("ECS_TASK_ARN"),
"containerName": os.environ.get("ECS_CONTAINER_NAME"),
})
logger.info("Processing order", {
"orderId": request.json["orderId"],
"amount": request.json["amount"],
})defsqs_handler(event):
forrecordinevent["Records"]:
logger.add_sqs_record_context(record)
logger.info("Processing order", {
"messageId": record["messageId"],
"attempt": record["attributes"]["ApproximateReceiveCount"],
})
# Logger maintains context throughout async operationsprocess_order(record["body"])Errors are automatically serialized with full context:
try:
risky_operation()
exceptExceptionaserror:
logger.error("Operation failed", error, {"context": "additional-info"})
# Includes: error message, stack trace, error type, and your context# Add user context that persists across logslogger.add_user_context({"id": "user-123", "role": "admin"})
# Add telemetry for performance trackinglogger.add_telemetry_fields({"duration": 150, "operation": "db-query"})
# Add custom context for specific logslogger.info("Payment processed", {
"amount": 99.99,
"currency": "USD",
})logger=AwsServerLogger(
pretty_print=True# Readable console output for development
)Logs are automatically saved to disk in development with smart rotation:
# Auto-enabled in local environments# Saves to .smooai-logs/ with ANSI colors for easy readinglogger=AwsServerLogger(
rotation={
"size": "10M", # Rotate at 10MB"interval": "1d", # Daily rotation"compress": True, # Gzip old logs
}
)TRACE- Detailed debugging informationDEBUG- Diagnostic informationINFO- General operational informationWARN- Warning conditionsERROR- Error conditionsFATAL- Critical failures
MINIMAL- Essential context onlyFULL- All available context (default)
- Python 3.8+ - Full type hints support
- AWS SDK Integration - Native support for Lambda, ECS, EC2, and more
- Automatic environment detection
- Smart log rotation
- @smooai/logger - TypeScript/JavaScript version
- smooai-logger (Rust) - Rust version
uv run poe install-dev
uv run pytest
uv run poe lint
uv run poe lint:fix # optional fixer
uv run poe format
uv run poe typecheck
uv run poe buildSet UV_PUBLISH_TOKEN before running uv run poe publish to upload to PyPI.
Brent Rager
Smoo Github: https://github.com/SmooAI
MIT © SmooAI