Install & Compatibility
Where this runs
tested against v2.4.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.004s · 19.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.002s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Tracer
✓ from opentracing import Tracer
Span
✓ from opentracing import Span
SpanContext
✓ from opentracing import SpanContext
Reference
✓ from opentracing import Reference
Format
✓ from opentracing.propagation import Format
✗ from opentracing import Format
The Format enum is located in the `propagation` submodule.
global_tracer
✓ from opentracing import global_tracer
✗ opentracing.tracer
The global tracer is accessed via `opentracing.global_tracer()` or set via `opentracing.set_global_tracer()`.
MockTracer
✓ from opentracing.mocktracer import MockTracer
ScopeManager (e.g., ThreadLocalScopeManager)
✓ from opentracing.scope_managers.thread_local import ThreadLocalScopeManager
Specific scope managers are imported from the `scope_managers` submodule, depending on the concurrency model.
This quickstart demonstrates how to initialize a MockTracer (for testing), set it as the global tracer, and then create nested spans using `start_active_span` with context managers. In a production environment, `MockTracer` would be replaced by a specific tracer client (e.g., `JaegerTracer`, `ZipkinTracer`) that exports telemetry data to a tracing backend.
import opentracing
from opentracing.mocktracer import MockTracer
# 1. Initialize a Tracer implementation (e.g., MockTracer for testing)
# In a real application, you would use a concrete tracer like JaegerTracer.
tracer = MockTracer()
opentracing.set_global_tracer(tracer)
# 2. Start a root span
with opentracing.global_tracer().start_active_span('root_operation') as scope:
root_span = scope.span
root_span.set_tag('component', 'quickstart_example')
root_span.log_kv({'event': 'started root operation'})
# 3. Create a child span
with opentracing.global_tracer().start_active_span('child_operation') as child_scope:
child_span = child_scope.span
child_span.set_tag('type', 'internal_call')
child_span.log_kv({'event': 'executing child logic'})
root_span.log_kv({'event': 'finished root operation'})
# For MockTracer, retrieve finished spans for assertion
finished_spans = tracer.finished_spans
assert len(finished_spans) == 2
assert finished_spans[0].operation_name == 'child_operation'
assert finished_spans[1].operation_name == 'root_operation'
print(f"Captured {len(finished_spans)} spans:")
for span in finished_spans:
print(f" - {span.operation_name}, Tags: {span.tags}, Logs: {span.logs}")
Debug
Known issues
breakingThe OpenTracing project has been officially archived by the CNCF and its functionality is now superseded by OpenTelemetry. New projects should implement OpenTelemetry directly.fixFor new projects, use OpenTelemetry. For existing OpenTracing projects, plan a migration to OpenTelemetry. OpenTelemetry provides an OpenTracing shim for backward compatibility during transitional phases.
affects: All versions, as this reflects project status
gotchaThe `opentracing` library itself provides only an API and a no-op (no operation) tracer implementation. To actually collect and export trace data, you must install and configure a specific OpenTracing-compatible tracer implementation (e.g., `jaeger-client`, `zipkin-opentracing`).fixInstall a concrete tracer library (e.g., `pip install jaeger-client`) and initialize it, then set it as the global tracer: `opentracing.set_global_tracer(your_actual_tracer)`.
affects: All versions
breakingVersion 2.0.0 introduced `Scope` and `ScopeManager` for in-process context propagation. This was a breaking change, altering how active spans are managed. `Tracer.start_span()` now automatically uses the current active Span as a parent unless `ignore_active_span=True` is explicitly set.fixReview span parenting logic; explicitly use `child_of` or `ignore_active_span=True` if the default auto-parenting behavior is not desired. Adapt code to use `start_active_span()` and context managers for simpler span lifecycle management.
affects: 2.0.0 and later
gotchaWhen using `multiprocessing` in Python, the tracer initialized in the parent process is not automatically inherited or re-initialized in child processes. This can lead to child process spans not being reported.fixEnsure that the OpenTracing tracer (and its underlying implementation) is initialized *within each child process* after the fork, rather than once in the parent process.
affects: All versions when using multiprocessing
Errors
Common errors & fixes
OpenTracing Support is now deprecated by Cloud Native Computing Foundation and is replaced by OpenTelemetry. We recommend moving over to Open Telemetry.
OpenTracing has been officially archived by the CNCF and its functionality has been superseded by OpenTelemetry, which is now the recommended standard for new projects and migrations from OpenTracing.
fixMigrate your tracing instrumentation from OpenTracing to OpenTelemetry, following the OpenTelemetry Python documentation for instrumentation and exporters.
ModuleNotFoundError: No module named 'six'
The `opentracing-python` library, especially older versions or its dependencies, might rely on the `six` compatibility library, which might not be installed in the environment.
fixInstall the `six` library using pip: `pip install six`.
AttributeError: 'Tracer' object has no attribute '_noop_scope'
This error typically occurs when an `opentracing` compatible tracer (like `jaeger_client.Config.initialize_tracer()`) is not correctly initialized or configured, leading to a default 'no-op' tracer being used in an unexpected way by an instrumentation library (e.g., `flask-opentracing`).
fixEnsure your tracer is properly initialized and globally registered (e.g., `opentracing.tracer = your_initialized_tracer`) before any instrumentation libraries attempt to use it. Verify the specific initialization steps required by your chosen tracer implementation (e.g., `jaeger-client`).
opentracing.UnsupportedFormatException or opentracing.InvalidCarrierException
These exceptions are raised when the `tracer.inject()` or `tracer.extract()` methods are called with an unsupported carrier format or when the carrier object itself is malformed or invalid for the specified format.
fixEnsure that the `format` argument passed to `inject()` or `extract()` is one of the supported `opentracing.propagation.Format` values (e.g., `Format.HTTP_HEADERS`, `Format.TEXT_MAP`) and that the `carrier` object is correctly structured for that format (e.g., a dictionary for `HTTP_HEADERS`). Validate the contents of the carrier if parsing externally received data.
Upgrade
Version history
2.4.0latest on PyPI · released Nov 19, 2020
Audit
Dependencies
No dependency data recorded yet.