{"id":907,"library":"opencensus","title":"OpenCensus Python","description":"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.","status":"maintenance","version":"0.11.4","language":"python","source_language":"en","source_url":"https://github.com/census-instrumentation/opencensus-python","tags":["observability","tracing","metrics","monitoring","telemetry"],"install":[{"cmd":"pip install opencensus","lang":"bash","label":"Core library"},{"cmd":"pip install opencensus-ext-azure","lang":"bash","label":"Example: Azure Exporter"}],"dependencies":[{"reason":"Common extension for exporting telemetry to Azure Monitor.","package":"opencensus-ext-azure","optional":true},{"reason":"For tracing HTTP requests made with the `requests` library.","package":"opencensus-ext-requests","optional":true},{"reason":"For integrating with Flask applications.","package":"opencensus-ext-flask","optional":true},{"reason":"For integrating with Django applications.","package":"opencensus-ext-django","optional":true}],"imports":[{"symbol":"Tracer","correct":"from opencensus.trace.tracer import Tracer"},{"symbol":"AlwaysOnSampler","correct":"from opencensus.trace.samplers import AlwaysOnSampler"},{"note":"Exporters are typically found directly under `opencensus.trace.exporters`.","wrong":"from opencensus.trace.exporters.print_exporter import PrintExporter","symbol":"PrintExporter","correct":"from opencensus.trace.exporters import PrintExporter"},{"symbol":"stats","correct":"from opencensus.stats import stats as stats_module"}],"quickstart":{"code":"from opencensus.trace.tracer import Tracer\nfrom opencensus.trace.samplers import AlwaysOnSampler\nfrom opencensus.trace.exporters import PrintExporter\n\ndef my_function_to_trace():\n    print(\"Doing some work inside the traced function...\")\n\n# Initialize a tracer with an exporter and a sampler\nexporter = PrintExporter()\ntracer = Tracer(exporter=exporter, sampler=AlwaysOnSampler())\n\n# Use the tracer to create a span\nwith tracer.span(name='my_parent_span') as span:\n    span.add_annotation('Starting my_parent_span operation')\n    print(f\"Current Span ID: {span.span_id}\")\n\n    with tracer.span(name='my_child_span') as child_span:\n        child_span.add_annotation('Starting my_child_span operation')\n        my_function_to_trace()\n        child_span.add_annotation('Finished my_child_span operation')\n\n    span.add_annotation('Finished my_parent_span operation')\nprint(\"Traced operations complete.\")","lang":"python","description":"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."},"warnings":[{"fix":"Plan and execute migration to OpenTelemetry. Official bridge libraries are available for incremental transitions.","message":"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.","severity":"breaking","affected_versions":"All versions, regarding project longevity and support"},{"fix":"Consult the OpenTelemetry migration guide for OpenCensus, which outlines expected changes and provides a compatibility specification.","message":"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.","severity":"breaking","affected_versions":"All versions, for users migrating to OpenTelemetry"},{"fix":"Install specific `opencensus-ext-*` packages for desired integrations and exporters (e.g., `pip install opencensus-ext-flask opencensus-ext-azure`).","message":"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.","severity":"gotcha","affected_versions":"0.8.0+"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions with SQLAlchemy and database driver integrations"}],"env_vars":null,"search_vec":"'0.11.4':42 'applic':10 'backend':37 'broader':54 'chosen':36 'collect':9 'continu':49 'current':39 'data':30 'develop':17 'distribut':13 'enabl':16 'encourag':64 'export':32 'framework':7 'gain':19 'gather':28 'general':63 'librari':26 'merg':58 'metric':11,69 'migrat':66 'monitor':70 'observ':20,67 'opencensus':1,3,46,55 'opencensus-python':45 'opentelemetri':60 'project':56 'provid':25 'python':2,4,47 'repositori':48 'see':51 'system':23 'telemetri':29,71 'trace':14,68 'updat':52 'user':62 'version':40","created_at":"2026-03-29T06:07:10.601514+00:00","updated_at":"2026-04-17T15:06:34.438662+00:00","problems":[{"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`.","cause":"The main `opencensus` package or one of its required extension packages has not been installed in the Python environment.","error":"ModuleNotFoundError: No module named 'opencensus'"},{"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.","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`).","error":"ImportError: cannot import name 'X' from 'opencensus.Y'"},{"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.","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.","error":"AttributeError: 'NoneType' object has no attribute 'span'"},{"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.","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).","error":"OpenCensus traces not appearing in Stackdriver Trace (or Azure Monitor)"},{"fix":"Install the required exporter package using pip: `pip install opencensus-ext-google-cloud-monitoring` (or the relevant extension for your chosen backend).","cause":"The specific OpenCensus exporter extension module (e.g., `opencensus-ext-google-cloud-monitoring`) has not been installed.","error":"ModuleNotFoundError: No module named 'opencensus.ext.google_cloud_monitoring'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://opencensus.io","github":"https://github.com/census-instrumentation/opencensus-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opencensus/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}