0
# Log Export
1
2
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.
3
4
## Capabilities
5
6
### Azure Log Handler
7
8
Exports Python log messages as trace telemetry to Azure Monitor, preserving log levels, custom properties, and exception details.
9
10
```python { .api }
11
class AzureLogHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
12
"""
13
Handler for logging to Microsoft Azure Monitor.
14
15
Sends log records as trace telemetry to Azure Monitor, including support
16
for custom properties, exception tracking, and correlation IDs.
17
"""
18
19
def __init__(self, **options):
20
"""
21
Initialize the Azure log handler.
22
23
Args:
24
**options: Configuration options including connection_string,
25
instrumentation_key, export_interval, etc.
26
"""
27
28
def emit(self, record):
29
"""
30
Emit a log record to Azure Monitor.
31
32
Args:
33
record (LogRecord): Python logging record to export
34
"""
35
36
def close(self, timeout=None):
37
"""
38
Close the handler and flush remaining telemetry.
39
40
Args:
41
timeout (float, optional): Maximum time to wait for flush
42
"""
43
44
def add_telemetry_processor(self, processor):
45
"""
46
Add a telemetry processor for filtering/modifying telemetry.
47
48
Args:
49
processor (callable): Function that takes and returns envelope
50
"""
51
52
def log_record_to_envelope(self, record):
53
"""
54
Convert a log record to Azure Monitor envelope.
55
56
Args:
57
record (LogRecord): Python logging record
58
59
Returns:
60
Envelope: Azure Monitor telemetry envelope
61
"""
62
```
63
64
#### Usage Example
65
66
```python
67
import logging
68
from opencensus.ext.azure.log_exporter import AzureLogHandler
69
70
# Basic configuration
71
handler = AzureLogHandler(
72
connection_string="InstrumentationKey=your-instrumentation-key"
73
)
74
75
# Configure logging
76
logger = logging.getLogger(__name__)
77
logger.addHandler(handler)
78
logger.setLevel(logging.INFO)
79
80
# Standard logging - sent as trace telemetry
81
logger.info("Application started")
82
logger.warning("Configuration issue detected")
83
84
# Exception logging - sent as exception telemetry
85
try:
86
result = 1 / 0
87
except ZeroDivisionError:
88
logger.error("Division by zero error", exc_info=True)
89
90
# Custom properties
91
logger.info("User action", extra={
92
'custom_dimensions': {
93
'user_id': '12345',
94
'action': 'login',
95
'success': True
96
}
97
})
98
```
99
100
### Azure Event Handler
101
102
Exports Python log messages as custom event telemetry to Azure Monitor, specifically designed for tracking application events and user actions.
103
104
```python { .api }
105
class AzureEventHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
106
"""
107
Handler for sending custom events to Microsoft Azure Monitor.
108
109
Sends log records as custom event telemetry, ideal for tracking
110
user actions, business events, and application milestones.
111
"""
112
113
def __init__(self, **options):
114
"""
115
Initialize the Azure event handler.
116
117
Args:
118
**options: Configuration options including connection_string,
119
instrumentation_key, export_interval, etc.
120
"""
121
122
def emit(self, record):
123
"""
124
Emit a log record as a custom event to Azure Monitor.
125
126
Args:
127
record (LogRecord): Python logging record to export as event
128
"""
129
130
def close(self, timeout=None):
131
"""
132
Close the handler and flush remaining telemetry.
133
134
Args:
135
timeout (float, optional): Maximum time to wait for flush
136
"""
137
138
def add_telemetry_processor(self, processor):
139
"""
140
Add a telemetry processor for filtering/modifying telemetry.
141
142
Args:
143
processor (callable): Function that takes and returns envelope
144
"""
145
146
def log_record_to_envelope(self, record):
147
"""
148
Convert a log record to Azure Monitor event envelope.
149
150
Args:
151
record (LogRecord): Python logging record
152
153
Returns:
154
Envelope: Azure Monitor event telemetry envelope
155
"""
156
```
157
158
#### Usage Example
159
160
```python
161
import logging
162
from opencensus.ext.azure.log_exporter import AzureEventHandler
163
164
# Configure event handler
165
event_handler = AzureEventHandler(
166
connection_string="InstrumentationKey=your-instrumentation-key"
167
)
168
169
# Create dedicated logger for events
170
event_logger = logging.getLogger('events')
171
event_logger.addHandler(event_handler)
172
event_logger.setLevel(logging.INFO)
173
174
# Track business events
175
event_logger.info("UserLogin", extra={
176
'custom_dimensions': {
177
'user_id': 'user123',
178
'login_method': 'oauth',
179
'success': True
180
},
181
'custom_measurements': {
182
'login_time_ms': 245,
183
'attempt_count': 1
184
}
185
})
186
187
# Track application milestones
188
event_logger.info("FeatureUsage", extra={
189
'custom_dimensions': {
190
'feature_name': 'advanced_search',
191
'user_tier': 'premium'
192
},
193
'custom_measurements': {
194
'search_results': 15,
195
'search_time_ms': 180
196
}
197
})
198
```
199
200
### Base Log Handler
201
202
Abstract base class providing common functionality for all Azure log handlers.
203
204
```python { .api }
205
class BaseLogHandler(logging.Handler):
206
"""
207
Base class for Azure log handlers providing common functionality.
208
"""
209
210
def __init__(self, **options):
211
"""
212
Initialize the base log handler.
213
214
Args:
215
**options: Configuration options
216
"""
217
218
def _export(self, batch, event=None):
219
"""
220
Export a batch of log records to Azure Monitor.
221
222
Args:
223
batch (list): List of log records to export
224
event (QueueEvent, optional): Synchronization event
225
"""
226
227
def close(self, timeout=None):
228
"""
229
Close the handler and clean up resources.
230
231
Args:
232
timeout (float, optional): Maximum time to wait for cleanup
233
"""
234
235
def flush(self, timeout=None):
236
"""
237
Flush any pending telemetry.
238
239
Args:
240
timeout (float, optional): Maximum time to wait for flush
241
"""
242
243
def apply_telemetry_processors(self, envelopes):
244
"""
245
Apply registered telemetry processors to envelopes.
246
247
Args:
248
envelopes (list): List of telemetry envelopes
249
250
Returns:
251
list: Processed envelopes
252
"""
253
```
254
255
### Sampling Filter
256
257
Built-in logging filter for controlling telemetry sampling rates.
258
259
```python { .api }
260
class SamplingFilter(logging.Filter):
261
"""
262
Logging filter that implements probabilistic sampling.
263
"""
264
265
def __init__(self, probability=1.0):
266
"""
267
Initialize the sampling filter.
268
269
Args:
270
probability (float): Sampling probability between 0.0 and 1.0
271
"""
272
273
def filter(self, record):
274
"""
275
Determine if a record should be processed.
276
277
Args:
278
record (LogRecord): Log record to evaluate
279
280
Returns:
281
bool: True if record should be processed
282
"""
283
```
284
285
## Configuration Options
286
287
Log exporters support these specific options in addition to common options:
288
289
- `logging_sampling_rate` (float): Sampling rate for log records (0.0 to 1.0, default: 1.0)
290
- `grace_period` (float): Time to wait for clean shutdown (default: 5.0 seconds)
291
- `queue_capacity` (int): Maximum queued log records (default: 100)
292
293
## Custom Properties and Measurements
294
295
Both handlers support custom properties and measurements via the `extra` parameter:
296
297
- `custom_dimensions` (dict): String key-value pairs for categorization and filtering
298
- `custom_measurements` (dict): Numeric key-value pairs for metrics and analysis
299
300
## Correlation and Context
301
302
Log handlers automatically capture and include:
303
304
- **Operation ID**: Trace correlation identifier from OpenCensus context
305
- **Parent ID**: Parent span identifier for distributed tracing
306
- **Process Information**: Process name, module, file name, and line number
307
- **Log Level**: Python logging level mapped to Azure Monitor severity
308
309
## Error Handling
310
311
Log handlers implement robust error handling:
312
313
- **Network Issues**: Automatic retry with exponential backoff
314
- **Local Storage**: Optional persistence during connectivity issues
315
- **Queue Management**: Asynchronous processing prevents application blocking
316
- **Exception Safety**: Handler errors don't propagate to application code