{"id":3202,"library":"opentelemetry-propagator-ot-trace","title":"OpenTelemetry OT Trace Propagator","description":"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.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["observability","opentelemetry","tracing","propagation","jaeger","ot-trace"],"install":[{"cmd":"pip install opentelemetry-propagator-ot-trace","lang":"bash","label":"Install the propagator"}],"dependencies":[{"reason":"Required for OpenTelemetry API interfaces (e.g., trace context, propagators).","package":"opentelemetry-api","optional":false},{"reason":"Required for OpenTelemetry SDK components (e.g., TracerProvider, global context management).","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"OTTracePropagator","correct":"from opentelemetry.propagators.ot_trace import OTTracePropagator"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.propagators.ot_trace import OTTracePropagator\nfrom opentelemetry.propagate import set_global_textmap\nfrom opentelemetry.context import set_current, get_current\n\n# 1. Set the OT Trace propagator globally\n# This tells OpenTelemetry to use the OT Trace format for context propagation.\nset_global_textmap(OTTracePropagator())\n\n# 2. Basic tracer setup (required for any tracing to occur)\n# For a real application, replace ConsoleSpanExporter with a production exporter (e.g., OTLPSpanExporter)\nprovider = TracerProvider()\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 3. Get a tracer\ntracer = trace.get_tracer(__name__)\n\n# 4. Example: Create a span that would use the OT Trace context if propagated\nwith tracer.start_as_current_span(\"my-ot-trace-propagated-span\"):\n    print(\"This span is created with OT Trace propagation enabled.\")\n    \n    # Manually inject current context into a carrier (e.g., HTTP headers)\n    carrier = {}\n    propagator = OTTracePropagator()\n    propagator.inject(carrier)\n    print(f\"\\nInjected context (example 'uber-trace-id'): {carrier.get('uber-trace-id', 'N/A')}\")\n    \n    # Simulate receiving context (e.g., from an incoming HTTP request)\n    received_carrier = {'uber-trace-id': '1:2:3:4'}\n    extracted_context = propagator.extract(received_carrier)\n    \n    # Activate the extracted context for subsequent operations\n    token = set_current(extracted_context)\n    try:\n        with tracer.start_as_current_span(\"child-span-from-extracted-context\"):\n            print(\"Child span created using extracted OT Trace context.\")\n    finally:\n        set_current(token) # Restore previous context\n\nprint(\"\\nQuickstart finished.\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the release notes and migration guides for each new version. Plan for potential minor code adjustments upon upgrade.","message":"This 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.","severity":"gotcha","affected_versions":"0.x.x (all beta versions)"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure a `TracerProvider` is globally set (`opentelemetry.trace.set_tracer_provider`) and configured with appropriate processors and exporters alongside your propagator setup.","message":"Registering `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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}