0
# Metrics and Statistics
1

2
Comprehensive metrics collection, aggregation, and export functionality for monitoring application performance, resource usage, and business metrics. Provides measures, views, aggregations, and export capabilities.
3

4
## Capabilities
5

6
### Measures and Measurements
7

8
Define what to measure and record individual measurements for later aggregation and analysis.
9

10
```python { .api }
11
class BaseMeasure:
12
    """
13
    Base class for all measures.
14
    
15
    Parameters:
16
    - name: str, measure name/identifier
17
    - description: str, human-readable description
18
    - unit: str, measurement unit (e.g., "ms", "bytes", "1")
19
    """
20
    def __init__(self, name, description, unit=None): ...
21

22
    @property
23
    def name(self):
24
        """str: Measure name"""
25

26
    @property
27
    def description(self):
28
        """str: Measure description"""
29

30
    @property
31
    def unit(self):
32
        """str: Measurement unit"""
33

34
class MeasureInt(BaseMeasure):
35
    """
36
    Integer-valued measure for counting and discrete values.
37
    
38
    Parameters:
39
    - name: str, measure name
40
    - description: str, measure description  
41
    - unit: str, measurement unit
42
    """
43
    def __init__(self, name, description, unit=None): ...
44

45
class MeasureFloat(BaseMeasure):
46
    """
47
    Float-valued measure for continuous values and rates.
48
    
49
    Parameters:
50
    - name: str, measure name
51
    - description: str, measure description
52
    - unit: str, measurement unit
53
    """
54
    def __init__(self, name, description, unit=None): ...
55

56
class Measurement:
57
    """
58
    Individual measurement combining measure and value.
59
    
60
    Parameters:
61
    - measure: BaseMeasure, what is being measured
62
    - value: int/float, measured value
63
    """
64
    def __init__(self, measure, value): ...
65

66
    @property
67
    def measure(self):
68
        """BaseMeasure: What is being measured"""
69

70
    @property  
71
    def value(self):
72
        """int/float: Measured value"""
73

74
class MeasurementInt(Measurement):
75
    """Integer measurement."""
76
    def __init__(self, measure, value): ...
77

78
class MeasurementFloat(Measurement):
79
    """Float measurement."""
80
    def __init__(self, measure, value): ...
81
```
82

83
### Views and Aggregations
84

85
Define how measurements are aggregated over time and exported as metrics.
86

87
```python { .api }
88
class View:
89
    """
90
    Defines aggregation and tag keys for measurements.
91
    
92
    Parameters:
93
    - name: str, view name/identifier
94
    - description: str, human-readable description
95
    - columns: list, tag keys for grouping/filtering
96
    - measure: BaseMeasure, measure to aggregate
97
    - aggregation: Aggregation, how to aggregate measurements
98
    """
99
    def __init__(self, name, description, columns, measure, aggregation): ...
100

101
    @property
102
    def name(self):
103
        """str: View name"""
104

105
    @property
106
    def description(self):
107
        """str: View description"""
108

109
    @property
110
    def columns(self):
111
        """list: Tag keys for grouping"""
112

113
    @property
114
    def measure(self):
115
        """BaseMeasure: Measure being aggregated"""
116

117
    @property
118
    def aggregation(self):
119
        """Aggregation: Aggregation method"""
120

121
    def new_aggregation_data(self):
122
        """Create new aggregation data instance."""
123

124
    def get_metric_descriptor(self):
125
        """Get metric descriptor for this view."""
126

127
class SumAggregation:
128
    """
129
    Sum aggregation - adds all measurement values.
130
    
131
    Parameters:
132
    - sum: int/float, initial sum value
133
    """
134
    def __init__(self, sum=None): ...
135

136
    def new_aggregation_data(self, measure):
137
        """
138
        Create new sum aggregation data.
139
        
140
        Parameters:
141
        - measure: BaseMeasure, measure being aggregated
142
        
143
        Returns:
144
        SumAggregationData: Aggregation data instance
145
        """
146

147
    def get_metric_type(self, measure):
148
        """
149
        Get metric type for this aggregation.
150
        
151
        Parameters:
152
        - measure: BaseMeasure, measure being aggregated
153
        
154
        Returns:
155
        MetricDescriptorType: Appropriate metric type
156
        """
157

158
class CountAggregation:
159
    """
160
    Count aggregation - counts number of measurements.
161
    
162
    Parameters:
163
    - count: int, initial count value
164
    """
165
    def __init__(self, count=0): ...
166

167
    def new_aggregation_data(self, measure=None):
168
        """Create new count aggregation data."""
169

170
    def get_metric_type(self, measure):
171
        """Get metric type for count aggregation."""
172

173
class DistributionAggregation:
174
    """
175
    Distribution/histogram aggregation with configurable buckets.
176
    
177
    Parameters:
178
    - boundaries: list, bucket boundary values
179
    """
180
    def __init__(self, boundaries=None): ...
181

182
    def new_aggregation_data(self, measure=None):
183
        """Create new distribution aggregation data."""
184

185
    def get_metric_type(self, measure):
186
        """Get metric type for distribution aggregation."""
187

188
class LastValueAggregation:
189
    """
190
    Last value aggregation - keeps most recent measurement.
191
    
192
    Parameters:
193
    - value: int/float, initial value
194
    """
195
    def __init__(self, value=0): ...
196

197
    def new_aggregation_data(self, measure):
198
        """Create new last value aggregation data."""
199

200
    def get_metric_type(self, measure):
201
        """Get metric type for last value aggregation."""
202
```
203

204
### Stats Recording and Management
205

206
Core runtime classes that handle measurement recording, view management, and data collection workflows.
207

208
```python { .api }
209
class StatsRecorder:
210
    """
211
    Records measurements against registered views.
212
    
213
    The main interface for recording measurements in the stats system.
214
    """
215
    def __init__(self): ...
216
    
217
    def new_measurement_map(self):
218
        """
219
        Create a new measurement map for recording multiple measurements.
220
        
221
        Returns:
222
        MeasurementMap: New measurement map instance
223
        """
224

225
class MeasurementMap:
226
    """
227
    Collection of measurements that can be recorded atomically.
228
    
229
    Parameters:
230
    - measure_to_view_map: MeasureToViewMap, view mapping
231
    - attachments: dict, contextual information (optional)
232
    """
233
    def __init__(self, measure_to_view_map, attachments=None): ...
234
    
235
    def measure_int_put(self, measure, value):
236
        """
237
        Associate integer measure with value.
238
        
239
        Parameters:
240
        - measure: MeasureInt, integer measure
241
        - value: int, measurement value
242
        """
243
    
244
    def measure_float_put(self, measure, value):
245
        """
246
        Associate float measure with value.
247
        
248
        Parameters:
249
        - measure: MeasureFloat, float measure
250
        - value: float, measurement value
251
        """
252
    
253
    def measure_put_attachment(self, key, value):
254
        """
255
        Add contextual attachment information.
256
        
257
        Parameters:
258
        - key: str, attachment key
259
        - value: str, attachment value
260
        """
261
    
262
    def record(self, tags=None):
263
        """
264
        Record all measurements in this map.
265
        
266
        Parameters:
267
        - tags: TagMap, tags to associate with measurements (optional)
268
        """
269

270
class ViewManager:
271
    """
272
    Manages view registration and data collection.
273
    
274
    Central registry for views and their associated data collection.
275
    """
276
    def __init__(self): ...
277
    
278
    def register_view(self, view):
279
        """
280
        Register a view for data collection.
281
        
282
        Parameters:
283
        - view: View, view to register
284
        """
285
    
286
    def get_view(self, view_name):
287
        """
288
        Get view data by name.
289
        
290
        Parameters:
291
        - view_name: str, name of the view
292
        
293
        Returns:
294
        ViewData: View data if found, None otherwise
295
        """
296
    
297
    def get_all_exported_views(self):
298
        """
299
        Get all views marked for export.
300
        
301
        Returns:
302
        list: List of ViewData objects for exported views
303
        """
304
    
305
    def register_exporter(self, exporter):
306
        """
307
        Register a stats exporter.
308
        
309
        Parameters:
310
        - exporter: StatsExporter, exporter to register
311
        """
312
    
313
    def unregister_exporter(self, exporter):
314
        """
315
        Unregister a stats exporter.
316
        
317
        Parameters:
318
        - exporter: StatsExporter, exporter to unregister
319
        """
320

321
class ViewData:
322
    """
323
    Contains aggregated data for a specific view.
324
    
325
    Parameters:
326
    - view: View, associated view
327
    - start_time: datetime, data collection start time
328
    - end_time: datetime, data collection end time (optional)
329
    """
330
    def __init__(self, view, start_time, end_time=None): ...
331
    
332
    def start(self):
333
        """Set start time for data collection."""
334
    
335
    def end(self):
336
        """Set end time for data collection."""
337
    
338
    def record(self, context, value, timestamp, attachments=None):
339
        """
340
        Record a measurement value.
341
        
342
        Parameters:
343
        - context: tag context for the measurement
344
        - value: int/float, measured value
345
        - timestamp: datetime, measurement timestamp
346
        - attachments: dict, contextual attachments (optional)
347
        """
348
    
349
    @property
350
    def view(self):
351
        """View: Associated view definition"""
352
    
353
    @property
354
    def start_time(self):
355
        """datetime: Data collection start time"""
356
    
357
    @property
358
    def end_time(self):
359
        """datetime: Data collection end time"""
360

361
class BucketBoundaries:
362
    """
363
    Defines histogram bucket boundaries for distribution aggregations.
364
    
365
    Parameters:
366
    - boundaries: list, bucket boundary values in ascending order
367
    """
368
    def __init__(self, boundaries=None): ...
369
    
370
    def is_valid_boundaries(self, boundaries):
371
        """
372
        Validate that boundaries are in ascending order.
373
        
374
        Parameters:
375
        - boundaries: list, boundary values to validate
376
        
377
        Returns:
378
        bool: True if boundaries are valid
379
        """
380
    
381
    @property
382
    def boundaries(self):
383
        """list: Bucket boundary values"""
384
```
385

386
### Global Stats Interface
387

388
Singleton instance providing access to the stats recording and view management system.
389

390
```python { .api }
391
class _Stats:
392
    """
393
    Global stats instance providing access to recording and view management.
394
    
395
    This is the main entry point for the OpenCensus stats system.
396
    """
397
    def __init__(self): ...
398
    
399
    def get_metrics(self):
400
        """
401
        Get all metrics from registered views.
402
        
403
        Returns:
404
        iterator: Iterator over Metric objects
405
        """
406
    
407
    @property
408
    def stats_recorder(self):
409
        """StatsRecorder: Global stats recorder instance"""
410
    
411
    @property
412
    def view_manager(self):
413
        """ViewManager: Global view manager instance"""
414

415
# Global stats instance - the main interface for OpenCensus stats
416
stats = _Stats()
417
"""_Stats: Global stats instance for recording measurements and managing views"""
418

419
Convenient global interface for recording measurements and managing views.
420

421
```python { .api }
422
class _Stats:
423
    """Internal stats implementation providing recorder and view manager."""
424
    
425
    @property
426
    def stats_recorder(self):
427
        """StatsRecorder: Global measurement recorder"""
428

429
    @property
430
    def view_manager(self):
431
        """ViewManager: Global view registry"""
432

433
# Global stats instance
434
stats = _Stats()
435
```
436

437
### Metric Export Types
438

439
Structured data types for exporting metrics to various backends and monitoring systems.
440

441
```python { .api }
442
class LabelKey:
443
    """
444
    Label key with description for metric metadata.
445
    
446
    Parameters:
447
    - key: str, label key name
448
    - description: str, label description
449
    """
450
    def __init__(self, key, description): ...
451

452
    @property
453
    def key(self):
454
        """str: Label key name"""
455

456
    @property
457
    def description(self):
458
        """str: Label description"""
459

460
class LabelValue:
461
    """
462
    Label value for metric labeling.
463
    
464
    Parameters:
465
    - value: str, label value (None for missing labels)
466
    """
467
    def __init__(self, value=None): ...
468

469
    @property
470
    def value(self):
471
        """str: Label value"""
472

473
    def __eq__(self, other):
474
        """Compare label values for equality."""
475

476
    def __hash__(self):
477
        """Hash function for use in sets/dicts."""
478

479
class Metric:
480
    """
481
    Collection of time series data with metadata.
482
    
483
    Parameters:
484
    - descriptor: MetricDescriptor, metric type and schema
485
    - time_series: list, list of TimeSeries objects
486
    """
487
    def __init__(self, descriptor, time_series): ...
488

489
    @property
490
    def descriptor(self):
491
        """MetricDescriptor: Metric metadata"""
492

493
    @property
494
    def time_series(self):
495
        """list: Time series data points"""
496

497
class MetricDescriptor:
498
    """
499
    Defines metric type and schema.
500
    
501
    Parameters:
502
    - name: str, metric name
503
    - description: str, metric description
504
    - unit: str, measurement unit
505
    - type_: MetricDescriptorType, metric type
506
    - label_keys: list, available label keys
507
    """
508
    def __init__(self, name, description, unit, type_, label_keys): ...
509

510
    @property
511
    def name(self):
512
        """str: Metric name"""
513

514
    @property
515
    def description(self):
516
        """str: Metric description"""
517

518
    @property
519
    def unit(self):
520
        """str: Measurement unit"""
521

522
    @property
523
    def type(self):
524
        """MetricDescriptorType: Metric type"""
525

526
    @property
527
    def label_keys(self):
528
        """list: Available label keys"""
529

530
class MetricDescriptorType:
531
    """Enumeration of metric types."""
532
    GAUGE_INT64 = 1
533
    GAUGE_DOUBLE = 2
534
    GAUGE_DISTRIBUTION = 3
535
    CUMULATIVE_INT64 = 4
536
    CUMULATIVE_DOUBLE = 5
537
    CUMULATIVE_DISTRIBUTION = 6
538
    SUMMARY = 7
539

540
    @classmethod
541
    def to_type_class(cls, metric_descriptor_type):
542
        """
543
        Convert metric type to appropriate value class.
544
        
545
        Parameters:
546
        - metric_descriptor_type: int, metric type constant
547
        
548
        Returns:
549
        type: Appropriate value class
550
        """
551

552
class TimeSeries:
553
    """
554
    Time-varying values collection with labels.
555
    
556
    Parameters:
557
    - label_values: list, label values for this series
558
    - points: list, time-ordered measurement points
559
    - start_timestamp: str, series start time
560
    """
561
    def __init__(self, label_values, points, start_timestamp): ...
562

563
    @property
564
    def label_values(self):
565
        """list: Label values"""
566

567
    @property
568
    def points(self):
569
        """list: Measurement points"""
570

571
    @property
572
    def start_timestamp(self):
573
        """str: Series start time"""
574

575
    def check_points_type(self, type_class):
576
        """Validate that all points are of expected type."""
577

578
class Point:
579
    """
580
    Timestamped measurement point.
581
    
582
    Parameters:
583
    - value: Value, measurement value
584
    - timestamp: time, measurement time
585
    """
586
    def __init__(self, value, timestamp): ...
587

588
    @property
589
    def value(self):
590
        """Value: Measurement value"""
591

592
    @property
593
    def timestamp(self):
594
        """time: Measurement time"""
595
```
596

597
### Export Infrastructure
598

599
Manage metric producers and coordinate metric export to monitoring backends.
600

601
```python { .api }
602
class MetricProducer:
603
    """Base class for metric production."""
604
    
605
    def get_metrics(self):
606
        """
607
        Get current metrics.
608
        
609
        Returns:
610
        iterator: Iterator of Metric objects
611
        """
612

613
class MetricProducerManager:
614
    """
615
    Container for managing multiple metric producers.
616
    
617
    Parameters:
618
    - metric_producers: list, initial list of producers
619
    """
620
    def __init__(self, metric_producers=None): ...
621

622
    def add(self, metric_producer):
623
        """
624
        Add metric producer.
625
        
626
        Parameters:
627
        - metric_producer: MetricProducer, producer to add
628
        """
629

630
    def remove(self, metric_producer):
631
        """
632
        Remove metric producer.
633
        
634
        Parameters:
635
        - metric_producer: MetricProducer, producer to remove
636
        """
637

638
    def get_all(self):
639
        """
640
        Get all registered producers.
641
        
642
        Returns:
643
        set: Set of MetricProducer instances
644
        """
645

646
class StatsExporter:
647
    """Base class for stats exporters."""
648
    
649
    def on_register_view(self, view):
650
        """
651
        Called when view is registered.
652
        
653
        Parameters:
654
        - view: View, newly registered view
655
        """
656

657
    def emit(self, view_datas):
658
        """
659
        Export view data.
660
        
661
        Parameters:
662
        - view_datas: list, list of ViewData objects
663
        """
664
```
665

666
### Metric Transport
667

668
Periodic export of metrics with background processing and error handling.
669

670
```python { .api }
671
class PeriodicMetricTask:
672
    """
673
    Periodic metric export task.
674
    
675
    Parameters:
676
    - interval: float, export interval in seconds
677
    - function: callable, export function
678
    - args: tuple, function arguments
679
    - kwargs: dict, function keyword arguments
680
    - name: str, task name
681
    """
682
    def __init__(self, interval=None, function=None, args=None, kwargs=None, name=None): ...
683

684
    def run(self):
685
        """Start periodic metric export."""
686

687
    def close(self):
688
        """Stop periodic export and cleanup."""
689

690
def get_exporter_thread(metric_producers, exporter, interval=None):
691
    """
692
    Get running metric export task.
693
    
694
    Parameters:
695
    - metric_producers: list, metric producers to export
696
    - exporter: Exporter, export destination
697
    - interval: float, export interval in seconds
698
    
699
    Returns:
700
    PeriodicMetricTask: Running export task
701
    """
702

703
class TransportError(Exception):
704
    """Exception raised for transport-related errors."""
705
```
706

707
## Usage Examples
708

709
### Basic Measurements
710

711
```python
712
from opencensus.stats.stats import stats
713
from opencensus.stats.measure import MeasureInt, MeasureFloat
714
from opencensus.stats.view import View
715
from opencensus.stats.aggregation import CountAggregation, SumAggregation
716

717
# Create measures
718
request_count = MeasureInt("requests", "number of requests", "1")
719
request_latency = MeasureFloat("request_latency", "request latency", "ms")
720

721
# Create views
722
request_count_view = View(
723
    "request_count_total",
724
    "total number of requests", 
725
    [],  # no grouping tags
726
    request_count,
727
    CountAggregation()
728
)
729

730
latency_sum_view = View(
731
    "request_latency_sum",
732
    "sum of request latencies",
733
    ["method", "status"],  # group by HTTP method and status
734
    request_latency,
735
    SumAggregation()
736
)
737

738
# Register views
739
from opencensus.stats.stats import stats
740
stats.view_manager.register_view(request_count_view)
741
stats.view_manager.register_view(latency_sum_view)
742

743
# Record measurements
744
measurement_map = stats.stats_recorder.new_measurement_map()
745
measurement_map.measure_int_put(request_count, 1)
746
measurement_map.measure_float_put(request_latency, 45.2)
747
measurement_map.record()
748
```
749

750
### Tagged Measurements
751

752
```python
753
from opencensus.stats.stats import stats
754
from opencensus.tags import TagMap, TagKey, TagValue
755

756
# Create tag keys and values
757
method_key = TagKey("method")
758
status_key = TagKey("status")
759

760
method_value = TagValue("GET")
761
status_value = TagValue("200")
762

763
# Create tag map
764
tag_map = TagMap()
765
tag_map.insert(method_key, method_value)
766
tag_map.insert(status_key, status_value)
767

768
# Record measurement with tags
769
measurement_map = stats.stats_recorder.new_measurement_map()
770
measurement_map.measure_int_put(request_count, 1)
771
measurement_map.record(tag_map)
772
```
773

774
### Distribution Metrics
775

776
```python
777
from opencensus.stats.aggregation import DistributionAggregation
778

779
# Create distribution with custom bucket boundaries
780
latency_distribution = DistributionAggregation([
781
    0, 10, 50, 100, 200, 500, 1000, 2000, 5000
782
])
783

784
latency_dist_view = View(
785
    "request_latency_distribution",
786
    "distribution of request latencies",
787
    ["service", "endpoint"],
788
    request_latency,
789
    latency_distribution
790
)
791

792
stats.view_manager.register_view(latency_dist_view)
793

794
# Record measurements - they'll be bucketed automatically
795
for latency in [15, 45, 120, 350, 1200]:
796
    measurement_map = stats.stats_recorder.new_measurement_map()
797
    measurement_map.measure_float_put(request_latency, latency)
798
    measurement_map.record(tag_map)
799
```