OpenCensus Runtime Context

Common errors

• ModuleNotFoundError: No module named 'opencensus.context'

  cause The Python interpreter cannot find the 'opencensus.context' module, typically because the 'opencensus-context' library is not installed or not accessible in the current environment.
  fix Ensure the library is installed using pip: `pip install opencensus-context` or `pip install opencensus` (as `opencensus-context` is usually installed with `opencensus`).

• ModuleNotFoundError: No module named 'opencensus'

  cause The core 'opencensus' library, which includes 'opencensus-context' by default, is not installed or not found by the Python interpreter.
  fix Install the main OpenCensus library: `pip install opencensus`.

• TypeError: bases must be types

  cause This error often occurs due to conflicts with dependency versions, particularly with 'protobuf' when used with 'opencensus-ext-azure', affecting the wider OpenCensus ecosystem which includes 'opencensus-context'.
  fix Downgrade conflicting dependencies, for example, a common fix is to downgrade 'protobuf' to a version compatible with your 'opencensus' and related 'opencensus-ext' libraries, e.g., `pip install protobuf==3.20.3` or `pip install google-api-core==2.9.0`.

• error: subprocess-exited-with-error × python setup.py egg_info did not run successfully. ... ModuleNotFoundError: No module named 'version'

  cause This indicates an installation failure for `opencensus-context` (or a related OpenCensus package), often occurring with specific `pip` flags (like `--no-binary`) or in certain build environments, due to issues with package metadata generation.
  fix Try installing without `--no-binary` if it's being used. Ensure `setuptools` is up-to-date (`pip install --upgrade setuptools`). If packaging for a specific distribution, check for available source distributions or pre-built wheels.

• ImportError: cannot import name 'RuntimeContext' from 'opencensus.context'

  cause Developers often incorrectly try to import `RuntimeContext` directly from `opencensus.context`, but it is located in the `opencensus.common.runtime_context` module.
  fix Correct the import statement to `from opencensus.common.runtime_context import RuntimeContext`.

Warnings

• breaking OpenCensus has officially merged with OpenTracing to form OpenTelemetry, which is considered the next major version. Users are strongly encouraged to migrate to OpenTelemetry for active development, new features, and continued support. Most OpenCensus GitHub repositories (except `opencensus-python`) were archived on July 31st, 2023. [3, 9, 10, 12]
  Fix: Plan a migration to OpenTelemetry. Official bridge libraries are available for Python to help with incremental migration. Be aware of potential breaking changes due to semantic conventions, data model differences, and API feature differences. [3, 8, 9, 11]
• deprecated Azure Monitor OpenCensus exporters are on the path to deprecation and will be officially unsupported by September 2024. Users are advised to migrate to Azure Monitor OpenTelemetry Distro or exporters. [14]
  Fix: For Azure Monitor users, migrate to the Azure Monitor OpenTelemetry Distro or the Azure Monitor OpenTelemetry exporters. Note that Microsoft does not recommend or support the OpenTelemetry OpenCensus shim for Azure Monitor users. [14, 16]
• gotcha `opencensus-context` uses `contextvars` for Python 3.6+ for asyncio support and thread-local storage for older Python versions (2.7, 3.4, 3.5). This might lead to unexpected behavior if not accounted for when porting code between Python versions, especially with asynchronous patterns. [1, 2]
  Fix: Ensure that your target Python version's context propagation mechanism is understood, especially when dealing with concurrent or asynchronous code. For Python < 3.6, explicit context propagation might be more frequently required in complex scenarios.
• breaking OpenTelemetry-based monitoring for Python officially supports Python 3.7 and later. If you are using OpenCensus with Python 2.7, 3.4, 3.5, or 3.6, you will need to upgrade your Python version to migrate to OpenTelemetry-based solutions, as these older Python versions are end-of-life and unsupported by OpenTelemetry. [16]
  Fix: Upgrade your Python environment to 3.7 or later before attempting to migrate from OpenCensus to OpenTelemetry. If an upgrade is not feasible, OpenTelemetry solutions will not be officially supported.
• gotcha Attempting to access `RuntimeContext.current_context()` directly will result in an `AttributeError` because `current_context` is not a registered context slot. Context variables should be managed using `RuntimeContext.set_opencensus_context()` and `RuntimeContext.get_opencensus_context()`.
  Fix: Use `RuntimeContext.set_opencensus_context('key', value)` and `RuntimeContext.get_opencensus_context('key')` to manage context variables.

Install

• pip install opencensus-context Install `opencensus-context`

Imports

• RuntimeContext

  from opencensus.common.runtime_context import RuntimeContext

Quickstart

This example demonstrates how to explicitly propagate the runtime context to a new thread using `RuntimeContext.with_current_context`. By default, context propagation happens automatically within a process, following control flow for threads and asynchronous coroutines. The context is a dictionary-like object. [1, 2]

from threading import Thread
from opencensus.common.runtime_context import RuntimeContext

def work(name):
    # The context is automatically propagated to new threads started via with_current_context
    current_context = RuntimeContext.current_context()
    print(f"Worker '{name}' in context: {current_context}")

# Create a context on the main thread
RuntimeContext.current_context()['request_id'] = 'main_req_123'

# Propagate context explicitly to a new thread
thread = Thread(
    target=RuntimeContext.with_current_context(work),
    args=('child_thread_A',),
)
thread.start()
thread.join()

# Another example with a simple function call in the current context
def another_work(name):
    current_context = RuntimeContext.current_context()
    print(f"Another worker '{name}' in context: {current_context}")

another_work('direct_call_B')