or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

common.mdexporters.mdindex.mdlogging.mdmetrics-stats.mdtags-context.mdtracing.md
tile.json

tessl/pypi-opencensus

A comprehensive observability framework providing distributed tracing, metrics collection, and statistics gathering capabilities for Python applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/opencensus@0.11.x

To install, run

npx @tessl/cli install tessl/pypi-opencensus@0.11.0

index.mddocs/

OpenCensus

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.

Package Information

  • Package Name: opencensus
  • Language: Python
  • Installation: pip install opencensus

Core Imports

import opencensus

For tracing (most common usage):

from opencensus.trace.tracer import Tracer
from opencensus.trace.span import Span
from opencensus.trace.samplers import ProbabilitySampler

For metrics:

from opencensus.stats import stats
from opencensus.stats.measure import MeasureInt, MeasureFloat
from opencensus.stats.view import View
from opencensus.stats.aggregation import CountAggregation, SumAggregation

For tags and context:

from opencensus.tags import TagMap, TagKey, TagValue
from opencensus.log import TraceLoggingAdapter

Basic Usage

from opencensus.trace.tracer import Tracer
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace import print_exporter

# Create a tracer with sampling and console export
tracer = Tracer(
    sampler=ProbabilitySampler(rate=1.0),
    exporter=print_exporter.PrintExporter()
)

# Create and manage spans
with tracer.span(name='my_operation') as span:
    span.add_attribute('user_id', '12345')
    span.add_annotation('Processing started')
    
    # Your application logic here
    result = process_data()
    
    span.add_attribute('result_count', len(result))
    span.add_annotation('Processing completed')

# Stats and metrics example
from opencensus.stats import stats
from opencensus.stats.measure import MeasureInt
from opencensus.stats.view import View
from opencensus.stats.aggregation import CountAggregation

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

# Register the view and record measurements
stats.view_manager.register_view(request_count_view)
measurement_map = stats.stats_recorder.new_measurement_map()
measurement_map.measure_int_put(request_count_measure, 1)
measurement_map.record()

Architecture

OpenCensus follows a modular architecture designed for flexibility and extensibility:

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

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

Capabilities

Distributed Tracing

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

class Tracer:
    def __init__(self, span_context=None, sampler=None, exporter=None, propagator=None): ...
    def span(self, name='span'): ...
    def should_sample(self): ...
    def finish(self): ...

class Span:
    def __init__(self, name, parent_span=None, attributes=None, start_time=None, 
                 end_time=None, span_id=None, context_tracer=None): ...
    def add_attribute(self, key, value): ...
    def add_annotation(self, description, timestamp=None, **attrs): ...
    def set_status(self, status): ...

Distributed Tracing

Metrics and Statistics

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

class MeasureInt:
    def __init__(self, name, description, unit=None): ...

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

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

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

class CountAggregation:
    def __init__(self, count=0): ...

Metrics and Statistics

Tags and Context Management

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

class TagMap:
    def __init__(self, tags=None): ...
    def insert(self, key, value): ...
    def update(self, key, value): ...
    def delete(self, key): ...

class TagKey:
    def __init__(self, name): ...

class TagValue:
    def __init__(self, value): ...

Tags and Context

Logging Integration

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

def get_log_attrs():
    """Get logging attributes from OpenCensus context"""

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

class TraceLogger:
    def makeRecord(self, *args, **kwargs): ...

Logging Integration

Exporters and Transports

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

class Exporter:
    def export(self, span_datas): ...
    def emit(self, span_datas): ...

class PrintExporter(Exporter): ...
class FileExporter(Exporter): ...
class LoggingExporter(Exporter): ...

class SyncTransport:
    def __init__(self, exporter): ...
    def export(self, datas): ...

class AsyncTransport:
    def __init__(self, exporter, grace_period=5.0, max_batch_size=600, wait_period=60.0): ...
    def export(self, data): ...

Exporters and Transports

Common Utilities

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

def load(expr):
    """Dynamically import OpenCensus components"""

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

class PeriodicTask:
    def __init__(self, interval, function, args=None, kwargs=None, name=None): ...
    def run(self): ...
    def cancel(self): ...

Common Utilities