tessl/pypi-opencensus-ext-azure
OpenCensus Azure Monitor Exporter for telemetry data (logs, metrics, and traces) to Azure Monitor.
—
Pending
log-export.mddocs/
Log Export
Python logging integration that sends log messages and exceptions to Azure Monitor. The log exporters provide seamless integration with Python's standard logging module, automatically capturing log records and transforming them into Azure Monitor telemetry.
Capabilities
Azure Log Handler
Exports Python log messages as trace telemetry to Azure Monitor, preserving log levels, custom properties, and exception details.
class AzureLogHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
"""
Handler for logging to Microsoft Azure Monitor.
Sends log records as trace telemetry to Azure Monitor, including support
for custom properties, exception tracking, and correlation IDs.
"""
def __init__(self, **options):
"""
Initialize the Azure log handler.
Args:
**options: Configuration options including connection_string,
instrumentation_key, export_interval, etc.
"""
def emit(self, record):
"""
Emit a log record to Azure Monitor.
Args:
record (LogRecord): Python logging record to export
"""
def close(self, timeout=None):
"""
Close the handler and flush remaining telemetry.
Args:
timeout (float, optional): Maximum time to wait for flush
"""
def add_telemetry_processor(self, processor):
"""
Add a telemetry processor for filtering/modifying telemetry.
Args:
processor (callable): Function that takes and returns envelope
"""
def log_record_to_envelope(self, record):
"""
Convert a log record to Azure Monitor envelope.
Args:
record (LogRecord): Python logging record
Returns:
Envelope: Azure Monitor telemetry envelope
"""Usage Example
import logging
from opencensus.ext.azure.log_exporter import AzureLogHandler
# Basic configuration
handler = AzureLogHandler(
connection_string="InstrumentationKey=your-instrumentation-key"
)
# Configure logging
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.INFO)
# Standard logging - sent as trace telemetry
logger.info("Application started")
logger.warning("Configuration issue detected")
# Exception logging - sent as exception telemetry
try:
result = 1 / 0
except ZeroDivisionError:
logger.error("Division by zero error", exc_info=True)
# Custom properties
logger.info("User action", extra={
'custom_dimensions': {
'user_id': '12345',
'action': 'login',
'success': True
}
})Azure Event Handler
Exports Python log messages as custom event telemetry to Azure Monitor, specifically designed for tracking application events and user actions.
class AzureEventHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
"""
Handler for sending custom events to Microsoft Azure Monitor.
Sends log records as custom event telemetry, ideal for tracking
user actions, business events, and application milestones.
"""
def __init__(self, **options):
"""
Initialize the Azure event handler.
Args:
**options: Configuration options including connection_string,
instrumentation_key, export_interval, etc.
"""
def emit(self, record):
"""
Emit a log record as a custom event to Azure Monitor.
Args:
record (LogRecord): Python logging record to export as event
"""
def close(self, timeout=None):
"""
Close the handler and flush remaining telemetry.
Args:
timeout (float, optional): Maximum time to wait for flush
"""
def add_telemetry_processor(self, processor):
"""
Add a telemetry processor for filtering/modifying telemetry.
Args:
processor (callable): Function that takes and returns envelope
"""
def log_record_to_envelope(self, record):
"""
Convert a log record to Azure Monitor event envelope.
Args:
record (LogRecord): Python logging record
Returns:
Envelope: Azure Monitor event telemetry envelope
"""Usage Example
import logging
from opencensus.ext.azure.log_exporter import AzureEventHandler
# Configure event handler
event_handler = AzureEventHandler(
connection_string="InstrumentationKey=your-instrumentation-key"
)
# Create dedicated logger for events
event_logger = logging.getLogger('events')
event_logger.addHandler(event_handler)
event_logger.setLevel(logging.INFO)
# Track business events
event_logger.info("UserLogin", extra={
'custom_dimensions': {
'user_id': 'user123',
'login_method': 'oauth',
'success': True
},
'custom_measurements': {
'login_time_ms': 245,
'attempt_count': 1
}
})
# Track application milestones
event_logger.info("FeatureUsage", extra={
'custom_dimensions': {
'feature_name': 'advanced_search',
'user_tier': 'premium'
},
'custom_measurements': {
'search_results': 15,
'search_time_ms': 180
}
})Base Log Handler
Abstract base class providing common functionality for all Azure log handlers.
class BaseLogHandler(logging.Handler):
"""
Base class for Azure log handlers providing common functionality.
"""
def __init__(self, **options):
"""
Initialize the base log handler.
Args:
**options: Configuration options
"""
def _export(self, batch, event=None):
"""
Export a batch of log records to Azure Monitor.
Args:
batch (list): List of log records to export
event (QueueEvent, optional): Synchronization event
"""
def close(self, timeout=None):
"""
Close the handler and clean up resources.
Args:
timeout (float, optional): Maximum time to wait for cleanup
"""
def flush(self, timeout=None):
"""
Flush any pending telemetry.
Args:
timeout (float, optional): Maximum time to wait for flush
"""
def apply_telemetry_processors(self, envelopes):
"""
Apply registered telemetry processors to envelopes.
Args:
envelopes (list): List of telemetry envelopes
Returns:
list: Processed envelopes
"""Sampling Filter
Built-in logging filter for controlling telemetry sampling rates.
class SamplingFilter(logging.Filter):
"""
Logging filter that implements probabilistic sampling.
"""
def __init__(self, probability=1.0):
"""
Initialize the sampling filter.
Args:
probability (float): Sampling probability between 0.0 and 1.0
"""
def filter(self, record):
"""
Determine if a record should be processed.
Args:
record (LogRecord): Log record to evaluate
Returns:
bool: True if record should be processed
"""Configuration Options
Log exporters support these specific options in addition to common options:
logging_sampling_rate(float): Sampling rate for log records (0.0 to 1.0, default: 1.0)grace_period(float): Time to wait for clean shutdown (default: 5.0 seconds)queue_capacity(int): Maximum queued log records (default: 100)
Custom Properties and Measurements
Both handlers support custom properties and measurements via the extra parameter:
custom_dimensions(dict): String key-value pairs for categorization and filteringcustom_measurements(dict): Numeric key-value pairs for metrics and analysis
Correlation and Context
Log handlers automatically capture and include:
- Operation ID: Trace correlation identifier from OpenCensus context
- Parent ID: Parent span identifier for distributed tracing
- Process Information: Process name, module, file name, and line number
- Log Level: Python logging level mapped to Azure Monitor severity
Error Handling
Log handlers implement robust error handling:
- Network Issues: Automatic retry with exponential backoff
- Local Storage: Optional persistence during connectivity issues
- Queue Management: Asynchronous processing prevents application blocking
- Exception Safety: Handler errors don't propagate to application code
Install with Tessl CLI
npx tessl i tessl/pypi-opencensus-ext-azure