0
# OpenCensus Azure Monitor Extension
1

2
OpenCensus Azure Monitor Extension provides comprehensive telemetry data export capabilities from OpenCensus instrumentation directly to Azure Monitor. The package enables Python applications to send logs, distributed traces, and metrics to Microsoft Azure Application Insights for monitoring, diagnostics, and performance analysis.
3

4
## Package Information
5

6
- **Package Name**: opencensus-ext-azure
7
- **Version**: 1.1.15
8
- **Language**: Python
9
- **Installation**: `pip install opencensus-ext-azure`
10
- **License**: Apache-2.0
11

12
## Core Imports
13

14
Primary importers for the three main exporters:
15

16
```python
17
from opencensus.ext.azure.log_exporter import AzureLogHandler, AzureEventHandler
18
from opencensus.ext.azure.trace_exporter import AzureExporter
19
from opencensus.ext.azure.metrics_exporter import MetricsExporter, new_metrics_exporter
20
```
21

22
Configuration and common utilities:
23

24
```python
25
from opencensus.ext.azure.common import Options
26
from opencensus.ext.azure.common.storage import LocalFileStorage, LocalFileBlob
27
from opencensus.ext.azure.common.protocol import (
28
    BaseObject, Envelope, Data, DataPoint, Event, ExceptionData, 
29
    Message, MetricData, Request, RemoteDependency
30
)
31
from opencensus.ext.azure.common.transport import TransportMixin, TransportStatusCode
32
from opencensus.ext.azure.common.processor import ProcessorMixin
33
from opencensus.ext.azure.common.utils import (
34
    validate_instrumentation_key, parse_connection_string, 
35
    azure_monitor_context, timestamp_to_duration, timestamp_to_iso_str
36
)
37
```
38

39
## Basic Usage
40

41
### Quick Start - Logging
42

43
```python
44
import logging
45
from opencensus.ext.azure.log_exporter import AzureLogHandler
46

47
# Configure the handler
48
handler = AzureLogHandler(connection_string="InstrumentationKey=your-key-here")
49
logging.getLogger().addHandler(handler)
50
logging.getLogger().setLevel(logging.INFO)
51

52
# Use standard Python logging
53
logging.info("This message will be sent to Azure Monitor")
54
logging.error("This error will be tracked as an exception", exc_info=True)
55
```
56

57
### Quick Start - Distributed Tracing
58

59
```python
60
from opencensus.trace.tracer import Tracer
61
from opencensus.ext.azure.trace_exporter import AzureExporter
62

63
# Configure the exporter
64
exporter = AzureExporter(connection_string="InstrumentationKey=your-key-here")
65
tracer = Tracer(exporter=exporter)
66

67
# Create and use spans
68
with tracer.span(name="my_operation") as span:
69
    span.add_attribute("key", "value")
70
    # Your application logic here
71
```
72

73
### Quick Start - Metrics
74

75
```python
76
from opencensus.ext.azure.metrics_exporter import new_metrics_exporter
77

78
# Create a configured exporter with standard metrics
79
exporter = new_metrics_exporter(
80
    connection_string="InstrumentationKey=your-key-here",
81
    enable_standard_metrics=True
82
)
83

84
# Standard metrics (CPU, memory, requests) are automatically collected
85
```
86

87
## Architecture
88

89
The OpenCensus Azure Monitor Extension follows a modular architecture:
90

91
- **Exporters**: Core classes that handle telemetry data transformation and transmission to Azure Monitor
92
- **Transport Layer**: HTTP communication with Azure Monitor endpoints, including retry logic and local storage
93
- **Storage Layer**: Optional local file persistence for reliability during network issues
94
- **Processing Layer**: Telemetry processors for data filtering and enrichment
95
- **Protocol Layer**: Azure Monitor telemetry protocol implementation and data serialization
96

97
Each exporter inherits common functionality from mixins while providing specialized telemetry type handling.
98

99
## Capabilities
100

101
### Log Export
102

103
Python logging integration that sends log messages and exceptions to Azure Monitor as trace telemetry and custom events.
104

105
```python { .api }
106
class AzureLogHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
107
    def __init__(self, **options): ...
108
    def emit(self, record): ...
109
    def close(self, timeout=None): ...
110
    def add_telemetry_processor(self, processor): ...
111

112
class AzureEventHandler(BaseLogHandler, TransportMixin, ProcessorMixin):
113
    def __init__(self, **options): ...
114
    def emit(self, record): ...
115
    def close(self, timeout=None): ...
116
    def add_telemetry_processor(self, processor): ...
117
```
118

119
[Log Export](./log-export.md)
120

121
### Trace Export
122

123
Distributed tracing export that sends OpenCensus span data to Azure Monitor for request tracking, dependency mapping, and performance analysis.
124

125
```python { .api }
126
class AzureExporter(BaseExporter, TransportMixin, ProcessorMixin):
127
    def __init__(self, **options): ...
128
    def export(self, span_datas): ...
129
    def span_data_to_envelope(self, span_data): ...
130
    def add_telemetry_processor(self, processor): ...
131
```
132

133
[Trace Export](./trace-export.md)
134

135
### Metrics Export
136

137
Performance counters and custom metrics collection with automatic standard metrics for system monitoring.
138

139
```python { .api }
140
class MetricsExporter(TransportMixin, ProcessorMixin):
141
    def __init__(self, is_stats=False, **options): ...
142
    def export_metrics(self, metrics): ...
143
    def metric_to_envelopes(self, metric): ...
144
    def shutdown(self): ...
145
    def add_telemetry_processor(self, processor): ...
146

147
def new_metrics_exporter(**options):
148
    """
149
    Factory function to create a fully configured metrics exporter.
150
    
151
    Args:
152
        **options: Configuration options for the exporter
153
        
154
    Returns:
155
        MetricsExporter: Configured exporter with background thread and standard metrics
156
    """
157
```
158

159
[Metrics Export](./metrics-export.md)
160

161
### Configuration and Common
162

163
Shared configuration options, utilities, protocol objects, and transport functionality used across all exporters.
164

165
```python { .api }
166
class Options(BaseObject):
167
    def __init__(self, **options): ...
168
    
169
def process_options(options): ...
170
def parse_connection_string(connection_string): ...
171
def validate_instrumentation_key(instrumentation_key): ...
172

173
class LocalFileStorage:
174
    def __init__(self, path, **options): ...
175
    def put(self, data, lease_period=0): ...
176
    def get(self): ...
177
    def close(self): ...
178

179
class LocalFileBlob:
180
    def __init__(self, fullpath): ...
181
    def get(self): ...
182
    def put(self, data, lease_period=0): ...
183
    def delete(self): ...
184

185
class TransportMixin:
186
    def _transmit(self, envelopes): ...
187
    def _transmit_from_storage(self): ...
188

189
class ProcessorMixin:
190
    def add_telemetry_processor(self, processor): ...
191
    def apply_telemetry_processors(self, envelopes): ...
192
```
193

194
[Configuration](./configuration.md)
195

196
## Common Configuration Options
197

198
All exporters accept these configuration parameters:
199

200
- `connection_string` (str): Azure Monitor connection string (recommended)
201
- `instrumentation_key` (str): Instrumentation key (deprecated, use connection_string)
202
- `endpoint` (str): Custom endpoint URL for Azure Monitor
203
- `export_interval` (float): Export frequency in seconds (default: 15.0)
204
- `max_batch_size` (int): Maximum batch size for telemetry (default: 100)
205
- `enable_local_storage` (bool): Enable local file storage for reliability (default: True)
206
- `storage_path` (str): Custom storage path for local files
207
- `timeout` (float): Network timeout in seconds (default: 10.0)
208
- `proxies` (dict): Proxy configuration for HTTP requests
209
- `credential`: Azure credential object for authentication
210

211
## Standard Metrics
212

213
When enabled, the metrics exporter automatically collects:
214

215
- **Process CPU Usage**: Processor time consumption
216
- **Available Memory**: System memory availability
217
- **Process Memory Usage**: Application memory consumption  
218
- **Request Rate**: Incoming request frequency
219
- **Request Average Execution Time**: Request processing duration
220

221
## Error Handling
222

223
All exporters may raise:
224

225
- `ValueError`: Invalid configuration options or parameters
226
- Network exceptions: During telemetry transmission (handled with retry logic)
227
- Storage exceptions: When local storage is enabled and encounters file system issues
228

229
## Dependencies
230

231
- `opencensus` >= 0.11.4, < 1.0.0
232
- `azure-core` >= 1.12.0, < 2.0.0  
233
- `azure-identity` >= 1.5.0, < 2.0.0
234
- `psutil` >= 5.6.3
235
- `requests` >= 2.19.0