semcore-structuredlogger 0.2.8

A structured logger based on structlog

Semcore Structured Logger

A Python package that provides structured logging capabilities with contextual information binding, built on top of structlog. Perfect for AWS Glue jobs, microservices, and any application requiring structured, searchable logs.

Features

• 🔧 Structured Logging: Log events with structured data using JSON format
• 📎 Context Binding: Attach application metadata and context to all log messages
• ⚡ Easy Integration: Simple API for initializing and using loggers
• ☁️ Cloud Ready: Designed to work seamlessly with AWS Glue jobs and cloud environments
• 📋 Rich Context: Automatic inclusion of timestamps, log levels, and call site information

Installation

Install from PyPI:

pip install semcore-structuredlogger

Quick Start

Basic Usage

from semcore_structuredlogger import StructuredLogger

# Initialize logger with application metadata
app_info = { 'app_prefix': 'ETL', 
             'app_description': 'data_processing_pipeline', 
             'app_type': 'aws_glue_job' }
logger = StructuredLogger(**name**, app_info)

# Log events with structured data
logger.log.info('Job started', job_id='123', status='running') 
logger.log.info('Data processed', records_count=1000, duration_ms=5000) 
logger.log.error('Processing failed', error_code='E001', table='users')

Context Binding

Bind context that persists across multiple log calls:

# Create a bound logger with persistent context
bound_logger = logger.log.bind(user_id='user_123', session_id='sess_456')
bound_logger.info('User logged in', action='login') 
bound_logger.info('Data fetched', action='data_fetch', records=250) 
bound_logger.warning('Rate limit approaching', current_requests=95, limit=100)

Sample Output

 { 
    "event": "Data processed", 
    "level": "info", 
    "timestamp": "2024-01-15T10:30:45.123456Z", 
    "func_name": "process_data", 
    "process_name": "MainProcess",
    "app_prefix": "ETL", 
    "app_description": "data_extraction_pipeline", 
    "app_type": "aws_glue_job", 
    "records_count": 1000, 
    "duration_ms": 5000 
 }

API Reference

StructuredLogger

The main logger class that provides structured logging capabilities.

Constructor

StructuredLogger(name: str, app_info: dict)

Parameters:

• name (str): Logger name, typically __name__ of your module
• app_info (dict): Application metadata that will be included in all log messages

Common app_info fields:

• app_prefix: Short application identifier
• app_description: Human-readable description
• app_type: Type of application (e.g., 'glue_job', 'api', 'batch')
• version: Application version
• environment: Runtime environment (e.g., 'dev', 'staging', 'prod')

Methods

The logger exposes a log attribute that provides all standard logging methods:

• logger.log.debug(message, **kwargs): Debug-level logging
• logger.log.info(message, **kwargs): Info-level logging
• logger.log.warning(message, **kwargs): Warning-level logging
• logger.log.error(message, **kwargs): Error-level logging
• logger.log.critical(message, **kwargs): Critical-level logging
• logger.log.bind(**kwargs): Create a bound logger with persistent context

Use Cases

AWS Glue Jobs

from semcore_structuredlogger import StructuredLogger

# Perfect for AWS Glue job logging
app_info = { 'app_prefix': 'ETL', 
             'app_description': 'daily_sales_processing', 
             'app_type': 'glue_job', 
             'version': '1.2.0' }
logger = StructuredLogger(**name**, app_info) 
logger.log.info('Glue job started', job_run_id='jr_123abc')

Microservices

# Great for microservice logging
app_info = { 'app_prefix': 'USER-SVC', 
              'app_description': 'User management service', 
              'app_type': 'microservice', 
              'version': '2.1.0', 
              'environment': 'production' }
logger = StructuredLogger(**name**, app_info)

Requirements

• Python >= 3.10
• structlog >= 25.5.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

0.2.8

• Basic structured logging functionality
• Context binding support
• AWS Glue job compatibility
• AWS Lambda compatibility

---

Built with ❤️ using structlog