Jaeger Protobuf gRPC Exporter for OpenTelemetry

Warnings

• gotcha The OpenTelemetry Python project uses a monorepo, where individual package versions on PyPI (e.g., `opentelemetry-exporter-jaeger-proto-grpc` v1.21.0) often differ from the overall project versions mentioned in GitHub release notes (e.g., v1.41.0). Always refer to the PyPI page for the specific package's version.
  Fix: Always check PyPI for the exact version of the package you intend to install and use.
• gotcha There are two distinct Jaeger exporters for OpenTelemetry Python: `opentelemetry-exporter-jaeger` (uses Thrift over HTTP/UDP) and `opentelemetry-exporter-jaeger-proto-grpc` (uses Protobuf over gRPC). Ensure you install and import the correct one for your Jaeger backend setup.
  Fix: Verify your Jaeger collector/agent configuration (Thrift vs. gRPC protocol) and choose the corresponding OpenTelemetry exporter package and import path.
• gotcha The Jaeger exporter requires a running Jaeger agent or collector reachable at the specified endpoint. If the agent/collector is not running or the endpoint is misconfigured, traces will not be exported, and the application might not raise explicit errors for this data loss.
  Fix: Ensure your Jaeger agent/collector is running and accessible from your application's host. Configure the exporter's endpoint using the `OTEL_EXPORTER_JAEGER_ENDPOINT` environment variable or the `endpoint` parameter in the `JaegerExporter` constructor (default is `localhost:14250`).
• gotcha The `grpcio` and `protobuf` dependencies are critical for this exporter. Occasionally, these packages can have complex installation requirements or version conflicts in highly constrained environments. Ensure they install correctly.
  Fix: Check for `grpcio` and `protobuf` specific installation issues if you encounter problems. Using a virtual environment is highly recommended. For M1 Macs, `grpcio` might require specific compilation flags or pre-built wheels.
• gotcha When manually shutting down the `TracerProvider` using `tracer_provider.shutdown()`, it's important to do so before your application exits. Otherwise, pending spans in the `BatchSpanProcessor` might not be flushed and could be lost.
  Fix: Always call `tracer_provider.shutdown()` at the graceful exit point of your application, for example, using a `atexit` hook or within a `try...finally` block in long-running services.

Install

• pip install opentelemetry-exporter-jaeger-proto-grpc Install stable version

Imports

• JaegerExporter

  from opentelemetry.exporter.jaeger.proto.grpc import JaegerExporter

  The other 'JaegerExporter' uses Thrift over HTTP/UDP, not Protobuf over gRPC.

Quickstart

This example demonstrates how to configure the OpenTelemetry SDK with the Jaeger Protobuf gRPC exporter. It sets up a TracerProvider, creates a JaegerExporter targeting a specified endpoint (defaulting to localhost:14250), and exports two simple spans. Ensure a Jaeger agent or collector is running and accessible at the configured endpoint.

import os

from opentelemetry import trace
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.jaeger.proto.grpc import JaegerExporter

# Configure tracing
resource = Resource.create({"service.name": os.environ.get("SERVICE_NAME", "my-python-app")})
tracer_provider = TracerProvider(resource=resource)

# Configure Jaeger Exporter (default endpoint: localhost:14250 for gRPC)
# Use OTEL_EXPORTER_JAEGER_ENDPOINT environment variable or endpoint param
jaeger_endpoint = os.environ.get("OTEL_EXPORTER_JAEGER_ENDPOINT", "localhost:14250")
jaeger_exporter = JaegerExporter(endpoint=jaeger_endpoint)

# Add the exporter to a BatchSpanProcessor and set it as the global tracer provider
span_processor = BatchSpanProcessor(jaeger_exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)

# Get a tracer and create a span
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-first-span"):
    with tracer.start_as_current_span("my-nested-span"):
        print("Hello from OpenTelemetry with Jaeger!")

# Manually shut down the tracer provider to ensure all spans are exported
tracer_provider.shutdown()
print(f"Traces exported to Jaeger endpoint: {jaeger_endpoint}")