Registry / observability / opentelemetry-propagator-ot-trace

opentelemetry-propagator-ot-trace

JSON →
library0.65b0pypypi✓ verified 23d ago

The `opentelemetry-propagator-ot-trace` library provides a TextMapPropagator for OpenTelemetry that allows traces to be propagated using the proprietary OT Trace context format (e.g., `uber-trace-id` header), which is often associated with older Jaeger clients. It's part of the `opentelemetry-python-contrib` project, currently at version `0.62b0`, and releases frequently alongside other contrib packages.

pip install opentelemetry-propagator-ot-trace
INSTALL
IMPORT
SIG · OPENTELEMETRY-PROP
O
opentelemetry-propagator-ot-trace
observabilitypythonv0.65b0
Install
2.1s avg
Import
102ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.65b0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.102s · 21.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.1s · import 0.102s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OTTracePropagator
from opentelemetry.propagators.ot_trace import OTTracePropagator

This quickstart demonstrates how to register the `OTTracePropagator` globally and use it within a basic OpenTelemetry tracing setup. It includes examples of injecting context into a carrier and extracting it to demonstrate the propagator's function. Ensure you have the `opentelemetry-sdk` installed for this example to run.

import os from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor from opentelemetry.propagators.ot_trace import OTTracePropagator from opentelemetry.propagate import set_global_textmap from opentelemetry.context import set_current, get_current # 1. Set the OT Trace propagator globally # This tells OpenTelemetry to use the OT Trace format for context propagation. set_global_textmap(OTTracePropagator()) # 2. Basic tracer setup (required for any tracing to occur) # For a real application, replace ConsoleSpanExporter with a production exporter (e.g., OTLPSpanExporter) provider = TracerProvider() processor = SimpleSpanProcessor(ConsoleSpanExporter()) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # 3. Get a tracer tracer = trace.get_tracer(__name__) # 4. Example: Create a span that would use the OT Trace context if propagated with tracer.start_as_current_span("my-ot-trace-propagated-span"): print("This span is created with OT Trace propagation enabled.") # Manually inject current context into a carrier (e.g., HTTP headers) carrier = {} propagator = OTTracePropagator() propagator.inject(carrier) print(f"\nInjected context (example 'uber-trace-id'): {carrier.get('uber-trace-id', 'N/A')}") # Simulate receiving context (e.g., from an incoming HTTP request) received_carrier = {'uber-trace-id': '1:2:3:4'} extracted_context = propagator.extract(received_carrier) # Activate the extracted context for subsequent operations token = set_current(extracted_context) try: with tracer.start_as_current_span("child-span-from-extracted-context"): print("Child span created using extracted OT Trace context.") finally: set_current(token) # Restore previous context print("\nQuickstart finished.")
Debug
Known issues
gotchaThis package is currently in beta (`0.62b0`). While OpenTelemetry strives for API stability, minor breaking changes might occur in future beta releases before a stable `1.x.x` version is released.
fix
Refer to the release notes and migration guides for each new version. Plan for potential minor code adjustments upon upgrade.
affects: 0.x.x (all beta versions)
gotchaThe `OTTracePropagator` implements a proprietary trace context format (e.g., `uber-trace-id` header) primarily used by older Jaeger clients. It is NOT compatible with the modern W3C Trace Context standard, which is the default for OpenTelemetry. Using this propagator will only exchange trace context with systems that understand the OT Trace format.
fix
For interoperability with most OpenTelemetry-compliant systems, use the default `W3CTraceContextPropagator` (often implicitly enabled) or `CompositeTextMapPropagator` if you need to support multiple formats. Only use `OTTracePropagator` when specifically integrating with legacy Jaeger systems.
affects: All versions
gotcha`set_global_textmap` modifies a global state. In applications with multiple isolated components, concurrent requests, or in test environments, this can lead to unexpected propagation behavior or conflicts if different parts of the application require different propagators.
fix
For fine-grained control or in complex environments, consider explicitly passing context via `opentelemetry.context.Context` objects rather than relying solely on global propagation. Ensure global settings are configured once at application startup, ideally within your application's entry point.
affects: All versions
gotchaRegistering `OTTracePropagator` via `set_global_textmap` only enables the *format* for context propagation. For actual traces to be collected and exported, you must also configure a `TracerProvider` with a `SpanProcessor` and an `Exporter`.
fix
Always ensure a `TracerProvider` is globally set (`opentelemetry.trace.set_tracer_provider`) and configured with appropriate processors and exporters alongside your propagator setup.
affects: All versions
Errors
Common errors & fixes
TypeError: expected string or bytes-like object
This error occurs when the `OTTracePropagator.extract` method is called with a carrier (e.g., a dictionary of headers) that does not contain the expected 'uber-trace-id' header, and the propagator attempts to process a `None` value as a string or bytes-like object.
fix
Ensure that the carrier dictionary passed to `extract` contains the 'uber-trace-id' key, even if its value is an empty string, or handle cases where the header might be missing gracefully before calling `extract`. The library's design should ideally not throw an exception in this scenario, as per OpenTelemetry specification. A fixed version of the library (after 0.61b0) should handle this automatically. If using an older version, ensure the carrier has the expected keys.
ModuleNotFoundError: No module named 'opentelemetry.propagators.ot_trace'
This error indicates that the `opentelemetry-propagator-ot-trace` package has not been installed, or it is not available in the Python environment where the code is being executed.
fix
Install the package using pip: `pip install opentelemetry-propagator-ot-trace`
Missing Trace IDs (or traces not correlating across services)
This is a common symptom when the `OTTracePropagator` (or any propagator) is not correctly configured and set as the global propagator in your OpenTelemetry SDK setup. Without a configured propagator, trace context cannot be injected into outgoing requests or extracted from incoming requests, leading to disconnected traces across services.
fix
Ensure the `OTTracePropagator` is set as the global propagator in your application's OpenTelemetry SDK initialization. For example:
```python
from opentelemetry import propagators
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.propagators.composite import CompositePropagator
from opentelemetry.propagators.ot_trace import OTTracePropagator

# Configure the tracer provider
provider = TracerProvider()
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)

# Set the global propagator
propagators.set_global_textmap(CompositePropagator([OTTracePropagator()]))

# Set the global tracer provider
from opentelemetry import trace
trace.set_tracer_provider(provider)

# Your application code
```
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredRequired for OpenTelemetry API interfaces (e.g., trace context, propagators).
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK components (e.g., TracerProvider, global context management).
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources