OpenCensus Python

0.11.4 · maintenance · verified Sun Mar 29

OpenCensus Python is a framework for collecting application metrics and distributed traces. It enables developers to gain observability into their systems by providing libraries to gather telemetry data and export it to a chosen backend. The current version is 0.11.4. While the `opencensus-python` repository continues to see updates, the broader OpenCensus project has merged into OpenTelemetry, with users generally encouraged to migrate.

Warnings

breaking OpenCensus has merged with OpenTracing to form OpenTelemetry, which is considered the next major version. Users are strongly encouraged to migrate to OpenTelemetry for future-proof observability solutions. While `opencensus-python` is an exception to the archiving of other OpenCensus repositories, the broader OpenCensus project does not receive new features or security patches since July 31, 2023.
Fix: Plan and execute migration to OpenTelemetry. Official bridge libraries are available for incremental transitions.
breaking Migration from OpenCensus to OpenTelemetry, even with bridge libraries, is considered a 'major version bump'. It may involve changes in import paths, method names, and telemetry data models.
Fix: Consult the OpenTelemetry migration guide for OpenCensus, which outlines expected changes and provides a compatibility specification.
gotcha OpenCensus Python originally shipped as a monolithic package. While core functionality remains in `opencensus`, integrations (e.g., Flask, Django, Requests) and many exporters are now provided as separate `opencensus-ext-*` packages. Installing the core library alone will not include these extensions.
Fix: Install specific `opencensus-ext-*` packages for desired integrations and exporters (e.g., `pip install opencensus-ext-flask opencensus-ext-azure`).
gotcha By default, OpenCensus traces are exported to `stdout` using the `PrintExporter`. To send telemetry data to a real backend (e.g., Azure Monitor, Stackdriver, Zipkin), you must explicitly configure and use the appropriate exporter.
Fix: Import and initialize a specific exporter (e.g., `StackdriverExporter`, `AzureExporter`) and pass it to the `Tracer` constructor. For example: `from opencensus.trace.exporters import StackdriverExporter; exporter = StackdriverExporter(); tracer = Tracer(exporter=exporter)`.
gotcha When integrating with database ORMs like SQLAlchemy, if you also enable tracing for the underlying database driver (e.g., `mysql`, `postgresql`), you may end up with duplicate spans for the same database operation.
Fix: It is recommended to only enable tracing for the SQLAlchemy integration (`'sqlalchemy'`) and disable tracing for the individual database driver to avoid redundant spans.

Install

pip install opencensus Core library
pip install opencensus-ext-azure Example: Azure Exporter

Imports

Tracer

from opencensus.trace.tracer import Tracer

AlwaysOnSampler

from opencensus.trace.samplers import AlwaysOnSampler

PrintExporter
```
from opencensus.trace.exporters import PrintExporter
```
Exporters are typically found directly under `opencensus.trace.exporters`.

stats

from opencensus.stats import stats as stats_module

Quickstart

This quickstart demonstrates how to initialize a basic tracer using the `PrintExporter` to output trace data to the console and create nested spans for tracing code execution.

from opencensus.trace.tracer import Tracer
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.exporters import PrintExporter

def my_function_to_trace():
    print("Doing some work inside the traced function...")

# Initialize a tracer with an exporter and a sampler
exporter = PrintExporter()
tracer = Tracer(exporter=exporter, sampler=AlwaysOnSampler())

# Use the tracer to create a span
with tracer.span(name='my_parent_span') as span:
    span.add_annotation('Starting my_parent_span operation')
    print(f"Current Span ID: {span.span_id}")

    with tracer.span(name='my_child_span') as child_span:
        child_span.add_annotation('Starting my_child_span operation')
        my_function_to_trace()
        child_span.add_annotation('Finished my_child_span operation')

    span.add_annotation('Finished my_parent_span operation')
print("Traced operations complete.")

view raw JSON →