OpenTelemetry OT Trace Propagator

Warnings

• gotcha 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.
  Fix: Refer to the release notes and migration guides for each new version. Plan for potential minor code adjustments upon upgrade.
• gotcha 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.
  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.
• 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.
• gotcha 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`.
  Fix: Always ensure a `TracerProvider` is globally set (`opentelemetry.trace.set_tracer_provider`) and configured with appropriate processors and exporters alongside your propagator setup.

Install

• pip install opentelemetry-propagator-ot-trace Install the propagator

Imports

• OTTracePropagator

  from opentelemetry.propagators.ot_trace import OTTracePropagator

Quickstart

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