OpenCensus Python

raw JSON →
0.11.4 verified Tue May 12 auth: no python install: verified maintenance

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.

pip install opencensus

Common errors

error ModuleNotFoundError: No module named 'opencensus' ↓
cause The main `opencensus` package or one of its required extension packages has not been installed in the Python environment.
fix
Install the core library using pip install opencensus. If using specific integrations (e.g., for Azure or Stackdriver), also install the relevant extension package, such as pip install opencensus-ext-azure or pip install opencensus-ext-stackdriver.
error ImportError: cannot import name 'X' from 'opencensus.Y' ↓
cause This error typically indicates that a specific module or class being imported from `opencensus` either does not exist at the specified path, has been moved in a different version, or there's a version incompatibility between `opencensus` and another library it integrates with (e.g., `sqlalchemy`).
fix
Verify the exact import path against the official OpenCensus Python documentation for your installed version. If using an extension library (like opencensus-ext-sqlalchemy), check its compatibility matrix with the version of the integrated library (e.g., sqlalchemy) you are using, and consider upgrading or downgrading dependencies as needed.
error AttributeError: 'NoneType' object has no attribute 'span' ↓
cause This usually happens when a `Tracer` or `Span` object, which is expected to be active, is `None`. This can occur if a `ProbabilitySampler` decides not to sample a given trace (resulting in a `None` span), or if the tracing context is not properly initialized or propagated, especially within custom middleware or complex application structures.
fix
During development or debugging, configure the tracer with an AlwaysOnSampler (e.g., tracer = Tracer(sampler=AlwaysOnSampler())) to ensure all traces are sampled and spans are always created. For production, ensure the tracing context is correctly managed and propagated throughout your application, especially in areas using custom middleware where the span might not be available in the execution context.
error OpenCensus traces not appearing in Stackdriver Trace (or Azure Monitor) ↓
cause Traces are being collected by OpenCensus but are not successfully exported to or displayed in the chosen backend. Common reasons include: the default probabilistic sampling rate is too low, traces are not being flushed by the exporter before the application exits, or there's an issue with authentication/configuration (e.g., incorrect project ID, missing environment variables in containerized environments, or an expired instrumentation key for Azure Monitor).
fix
Set the sampler to AlwaysOnSampler() during debugging to ensure all traces are sent. Manually call exporter.flush() before your application terminates. For Google Cloud, ensure GOOGLE_APPLICATION_CREDENTIALS or a service account with Cloud Trace Agent role is configured, and that CONTAINER_NAME and NAMESPACE environment variables are set in GKE. For Azure, verify the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable or the connection string in code is correct and valid.
error ModuleNotFoundError: No module named 'opencensus.ext.google_cloud_monitoring' ↓
cause The specific OpenCensus exporter extension module (e.g., `opencensus-ext-google-cloud-monitoring`) has not been installed.
fix
Install the required exporter package using pip: pip install opencensus-ext-google-cloud-monitoring (or the relevant extension for your chosen backend).

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-ext-azure

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk
3.10 alpine (musl) opencensus wheel - 0.18s 48.5M
3.10 alpine (musl) opencensus - - 0.19s 47.4M
3.10 alpine (musl) opencensus-ext-azure wheel - 0.19s 53.9M
3.10 alpine (musl) opencensus-ext-azure - - 0.16s 52.7M
3.10 slim (glibc) opencensus wheel 4.5s 0.07s 49M
3.10 slim (glibc) opencensus - - 0.07s 48M
3.10 slim (glibc) opencensus-ext-azure wheel 5.5s 0.07s 55M
3.10 slim (glibc) opencensus-ext-azure - - 0.07s 53M
3.11 alpine (musl) opencensus wheel - 0.52s 52.4M
3.11 alpine (musl) opencensus - - 0.63s 51.3M
3.11 alpine (musl) opencensus-ext-azure wheel - 0.52s 59.0M
3.11 alpine (musl) opencensus-ext-azure - - 0.58s 57.8M
3.11 slim (glibc) opencensus wheel 4.1s 0.13s 53M
3.11 slim (glibc) opencensus - - 0.15s 52M
3.11 slim (glibc) opencensus-ext-azure wheel 5.1s 0.13s 60M
3.11 slim (glibc) opencensus-ext-azure - - 0.13s 59M
3.12 alpine (musl) opencensus wheel - 0.44s 44.0M
3.12 alpine (musl) opencensus - - 0.48s 42.8M
3.12 alpine (musl) opencensus-ext-azure wheel - 0.43s 50.3M
3.12 alpine (musl) opencensus-ext-azure - - 0.47s 49.1M
3.12 slim (glibc) opencensus wheel 3.7s 0.12s 45M
3.12 slim (glibc) opencensus - - 0.13s 44M
3.12 slim (glibc) opencensus-ext-azure wheel 4.5s 0.12s 51M
3.12 slim (glibc) opencensus-ext-azure - - 0.12s 50M
3.13 alpine (musl) opencensus wheel - 0.39s 43.7M
3.13 alpine (musl) opencensus - - 0.44s 42.5M
3.13 alpine (musl) opencensus-ext-azure wheel - 0.36s 50.0M
3.13 alpine (musl) opencensus-ext-azure - - 0.43s 48.8M
3.13 slim (glibc) opencensus wheel 3.7s 0.11s 44M
3.13 slim (glibc) opencensus - - 0.13s 43M
3.13 slim (glibc) opencensus-ext-azure wheel 4.3s 0.11s 51M
3.13 slim (glibc) opencensus-ext-azure - - 0.12s 50M
3.9 alpine (musl) opencensus wheel - 0.11s 48.5M
3.9 alpine (musl) opencensus - - 0.12s 47.5M
3.9 alpine (musl) opencensus-ext-azure wheel - 0.11s 53.9M
3.9 alpine (musl) opencensus-ext-azure - - 0.12s 52.8M
3.9 slim (glibc) opencensus wheel 5.1s 0.09s 49M
3.9 slim (glibc) opencensus - - 0.08s 48M
3.9 slim (glibc) opencensus-ext-azure wheel 6.3s 0.10s 55M
3.9 slim (glibc) opencensus-ext-azure - - 0.08s 54M

Imports

Quickstart last tested: 2026-04-24

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.")
last verified Tue May 12
next check Sat Jun 27