0
# OpenCensus
1

2
A comprehensive observability framework that provides distributed tracing, metrics collection, and statistics gathering capabilities for Python applications. OpenCensus enables developers to instrument their applications to collect performance data, track requests across microservices, and monitor resource usage with integrations for popular exporters and frameworks.
3

4
## Package Information
5

6
- **Package Name**: opencensus
7
- **Language**: Python
8
- **Installation**: `pip install opencensus`
9

10
## Core Imports
11

12
```python
13
import opencensus
14
```
15

16
For tracing (most common usage):
17

18
```python
19
from opencensus.trace.tracer import Tracer
20
from opencensus.trace.span import Span
21
from opencensus.trace.samplers import ProbabilitySampler
22
```
23

24
For metrics:
25

26
```python
27
from opencensus.stats import stats
28
from opencensus.stats.measure import MeasureInt, MeasureFloat
29
from opencensus.stats.view import View
30
from opencensus.stats.aggregation import CountAggregation, SumAggregation
31
```
32

33
For tags and context:
34

35
```python
36
from opencensus.tags import TagMap, TagKey, TagValue
37
from opencensus.log import TraceLoggingAdapter
38
```
39

40
## Basic Usage
41

42
```python
43
from opencensus.trace.tracer import Tracer
44
from opencensus.trace.samplers import ProbabilitySampler
45
from opencensus.trace import print_exporter
46

47
# Create a tracer with sampling and console export
48
tracer = Tracer(
49
    sampler=ProbabilitySampler(rate=1.0),
50
    exporter=print_exporter.PrintExporter()
51
)
52

53
# Create and manage spans
54
with tracer.span(name='my_operation') as span:
55
    span.add_attribute('user_id', '12345')
56
    span.add_annotation('Processing started')
57
    
58
    # Your application logic here
59
    result = process_data()
60
    
61
    span.add_attribute('result_count', len(result))
62
    span.add_annotation('Processing completed')
63

64
# Stats and metrics example
65
from opencensus.stats import stats
66
from opencensus.stats.measure import MeasureInt
67
from opencensus.stats.view import View
68
from opencensus.stats.aggregation import CountAggregation
69

70
# Define a measure and view
71
request_count_measure = MeasureInt("requests", "number of requests", "1")
72
request_count_view = View("request_count", "number of requests", 
73
                         [], request_count_measure, CountAggregation())
74

75
# Register the view and record measurements
76
stats.view_manager.register_view(request_count_view)
77
measurement_map = stats.stats_recorder.new_measurement_map()
78
measurement_map.measure_int_put(request_count_measure, 1)
79
measurement_map.record()
80
```
81

82
## Architecture
83

84
OpenCensus follows a modular architecture designed for flexibility and extensibility:
85

86
- **Tracer**: Coordinates span creation, sampling decisions, and trace export
87
- **Spans**: Individual units of work in a trace with timing, attributes, and context
88
- **Samplers**: Control which traces are collected (probability, always-on/off)
89
- **Exporters**: Send trace and metrics data to various backends (console, files, cloud services)
90
- **Context Propagation**: Maintain trace context across service boundaries and threads
91
- **Stats/Metrics**: Collect and aggregate measurements with configurable views
92
- **Tags**: Key-value labels for organizing and filtering observability data
93

94
This design enables comprehensive observability across distributed systems while maintaining performance and providing extensive customization options.
95

96
## Capabilities
97

98
### Distributed Tracing 
99

100
Core tracing functionality including span creation, context management, sampling, and export. Provides the foundation for tracking requests across microservices and understanding application performance.
101

102
```python { .api }
103
class Tracer:
104
    def __init__(self, span_context=None, sampler=None, exporter=None, propagator=None): ...
105
    def span(self, name='span'): ...
106
    def should_sample(self): ...
107
    def finish(self): ...
108

109
class Span:
110
    def __init__(self, name, parent_span=None, attributes=None, start_time=None, 
111
                 end_time=None, span_id=None, context_tracer=None): ...
112
    def add_attribute(self, key, value): ...
113
    def add_annotation(self, description, timestamp=None, **attrs): ...
114
    def set_status(self, status): ...
115
```
116

117
[Distributed Tracing](./tracing.md)
118

119
### Metrics and Statistics
120

121
Metrics collection, aggregation, and export functionality for monitoring application performance and resource usage. Includes measures, views, and various aggregation types.
122

123
```python { .api }
124
class MeasureInt:
125
    def __init__(self, name, description, unit=None): ...
126

127
class MeasureFloat:
128
    def __init__(self, name, description, unit=None): ...
129

130
class View:
131
    def __init__(self, name, description, columns, measure, aggregation): ...
132

133
class SumAggregation:
134
    def __init__(self, sum=None): ...
135

136
class CountAggregation:
137
    def __init__(self, count=0): ...
138
```
139

140
[Metrics and Statistics](./metrics-stats.md)
141

142
### Tags and Context Management
143

144
Tag management and context propagation for organizing and filtering observability data across service boundaries and execution contexts.
145

146
```python { .api }
147
class TagMap:
148
    def __init__(self, tags=None): ...
149
    def insert(self, key, value): ...
150
    def update(self, key, value): ...
151
    def delete(self, key): ...
152

153
class TagKey:
154
    def __init__(self, name): ...
155

156
class TagValue:
157
    def __init__(self, value): ...
158
```
159

160
[Tags and Context](./tags-context.md)
161

162
### Logging Integration
163

164
Integration with Python's logging system to automatically include trace context in log records, enabling correlation between logs and traces.
165

166
```python { .api }
167
def get_log_attrs():
168
    """Get logging attributes from OpenCensus context"""
169

170
class TraceLoggingAdapter:
171
    def __init__(self, logger, extra=None): ...
172
    def process(self, msg, kwargs): ...
173

174
class TraceLogger:
175
    def makeRecord(self, *args, **kwargs): ...
176
```
177

178
[Logging Integration](./logging.md)
179

180
### Exporters and Transports
181

182
Export collected traces and metrics to various backends including console output, files, and cloud services. Includes both synchronous and asynchronous transport options.
183

184
```python { .api }
185
class Exporter:
186
    def export(self, span_datas): ...
187
    def emit(self, span_datas): ...
188

189
class PrintExporter(Exporter): ...
190
class FileExporter(Exporter): ...
191
class LoggingExporter(Exporter): ...
192

193
class SyncTransport:
194
    def __init__(self, exporter): ...
195
    def export(self, datas): ...
196

197
class AsyncTransport:
198
    def __init__(self, exporter, grace_period=5.0, max_batch_size=600, wait_period=60.0): ...
199
    def export(self, data): ...
200
```
201

202
[Exporters and Transports](./exporters.md)
203

204
### Common Utilities
205

206
Shared utilities including configuration management, resource detection, scheduling, and general helper functions used across the OpenCensus ecosystem.
207

208
```python { .api }
209
def load(expr):
210
    """Dynamically import OpenCensus components"""
211

212
class Resource:
213
    def __init__(self, type_=None, labels=None): ...
214
    def merge(self, other): ...
215

216
class PeriodicTask:
217
    def __init__(self, interval, function, args=None, kwargs=None, name=None): ...
218
    def run(self): ...
219
    def cancel(self): ...
220
```
221

222
[Common Utilities](./common.md)