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.
Install & Compatibility
Where this runs
tested against v0.11.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.950 runs
installs and imports cleanly · install 0.0s · import 0.340s · 53.9MB
glibcpy 3.10–3.950 runs
installs and imports cleanly · install 4.7s · import 0.106s · 55MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Tracer
✓ from opencensus.trace.tracer import Tracer
AlwaysOnSampler
✓ from opencensus.trace.samplers import AlwaysOnSampler
PrintExporter
✓ from opencensus.trace.exporters import PrintExporter
✗ from opencensus.trace.exporters.print_exporter import PrintExporter
Exporters are typically found directly under `opencensus.trace.exporters`.
stats
✓ from opencensus.stats import stats as stats_module
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.")
Debug
Known issues
breakingOpenCensus 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.fixPlan and execute migration to OpenTelemetry. Official bridge libraries are available for incremental transitions.
affects: All versions, regarding project longevity and support
breakingMigration 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.fixConsult the OpenTelemetry migration guide for OpenCensus, which outlines expected changes and provides a compatibility specification.
affects: All versions, for users migrating to OpenTelemetry
gotchaOpenCensus 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.fixInstall specific `opencensus-ext-*` packages for desired integrations and exporters (e.g., `pip install opencensus-ext-flask opencensus-ext-azure`).
affects: 0.8.0+
gotchaBy 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.fixImport 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)`.
affects: All versions
gotchaWhen 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.fixIt is recommended to only enable tracing for the SQLAlchemy integration (`'sqlalchemy'`) and disable tracing for the individual database driver to avoid redundant spans.
affects: All versions with SQLAlchemy and database driver integrations
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opencensus'
The main `opencensus` package or one of its required extension packages has not been installed in the Python environment.
fixInstall 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`.
ImportError: cannot import name 'X' from 'opencensus.Y'
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`).
fixVerify 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.
AttributeError: 'NoneType' object has no attribute 'span'
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.
fixDuring 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.
OpenCensus traces not appearing in Stackdriver Trace (or Azure Monitor)
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).
fixSet 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.
ModuleNotFoundError: No module named 'opencensus.ext.google_cloud_monitoring'
The specific OpenCensus exporter extension module (e.g., `opencensus-ext-google-cloud-monitoring`) has not been installed.
fixInstall the required exporter package using pip: `pip install opencensus-ext-google-cloud-monitoring` (or the relevant extension for your chosen backend).
Audit
Dependencies
opencensus-ext-azureoptionalCommon extension for exporting telemetry to Azure Monitor.
opencensus-ext-requestsoptionalFor tracing HTTP requests made with the `requests` library.
opencensus-ext-flaskoptionalFor integrating with Flask applications.
opencensus-ext-djangooptionalFor integrating with Django applications.