OpenTracing Python API

2.4.0 · deprecated · verified Sun Apr 12

OpenTracing is a vendor-neutral API for distributed tracing. This Python library (version 2.4.0) provides the OpenTracing API specification and a basic no-op implementation, requiring a concrete tracer implementation (e.g., Jaeger, Zipkin) for actual tracing data collection. The OpenTracing project has been officially archived by the CNCF, with its functionality superseded by OpenTelemetry. New projects are strongly encouraged to use OpenTelemetry, and existing users should plan for migration.

Warnings

breaking The OpenTracing project has been officially archived by the CNCF and its functionality is now superseded by OpenTelemetry. New projects should implement OpenTelemetry directly.
Fix: For new projects, use OpenTelemetry. For existing OpenTracing projects, plan a migration to OpenTelemetry. OpenTelemetry provides an OpenTracing shim for backward compatibility during transitional phases.
gotcha The `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`).
Fix: Install 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)`.
breaking Version 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.
Fix: Review 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.
gotcha When 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.
Fix: Ensure that the OpenTracing tracer (and its underlying implementation) is initialized *within each child process* after the fork, rather than once in the parent process.

Install

pip install opentracing Install OpenTracing API

Imports

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
```
The Format enum is located in the `propagation` submodule.
global_tracer
```
from opentracing import global_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.

Quickstart

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}")

view raw JSON →