OpenTelemetry Python API

Warnings

• breaking Installing only 'opentelemetry-api' gives silent no-ops. All tracing calls succeed without errors but nothing is recorded. Must also install 'opentelemetry-sdk'.
  Fix: pip install opentelemetry-api opentelemetry-sdk
• breaking trace.get_tracer() returns NoopTracer until trace.set_tracer_provider() is called. Forgetting this line means all spans are silently discarded. Warning: 'No TracerProvider configured, using NoopTracerProvider' only shows with debug logging enabled.
  Fix: Always call trace.set_tracer_provider(provider) after creating TracerProvider, before any trace.get_tracer() calls.
• breaking Exporters are separate packages not included in opentelemetry-sdk. OTLP requires 'opentelemetry-exporter-otlp'. Jaeger requires 'opentelemetry-exporter-jaeger'. ConsoleSpanExporter is included in SDK.
  Fix: pip install opentelemetry-exporter-otlp for production. Use ConsoleSpanExporter for local development.
• breaking All opentelemetry-* packages must be the same version. Mixing versions (e.g. api=1.20, sdk=1.25) causes ImportError or unexpected behavior.
  Fix: Pin all packages to same version: pip install 'opentelemetry-api==1.40.0' 'opentelemetry-sdk==1.40.0' 'opentelemetry-exporter-otlp==1.40.0'
• gotcha Auto-instrumentation packages (opentelemetry-instrumentation-fastapi etc.) are in the separate 'opentelemetry-python-contrib' repo — not in the main SDK. Must be installed separately.
  Fix: pip install opentelemetry-instrumentation-fastapi opentelemetry-instrumentation-sqlalchemy etc.
• gotcha provider.shutdown() must be called on app exit to flush buffered spans. Without it, spans in the BatchSpanProcessor queue are lost on process exit.
  Fix: Call provider.shutdown() in app shutdown handler or use atexit.register(provider.shutdown).
• gotcha service.name resource attribute is not set by default. Without it, traces appear as 'unknown_service' in your backend.
  Fix: Resource.create({'service.name': 'my-service'}) or set OTEL_SERVICE_NAME env var.

Install

• pip install opentelemetry-api opentelemetry-sdk Python (both required for actual tracing)
• pip install opentelemetry-exporter-otlp OTLP exporter (for Grafana, Datadog, Honeycomb, etc.)
• pip install opentelemetry-instrumentation-fastapi opentelemetry-instrumentation-sqlalchemy Auto-instrumentation packages (from contrib repo)

Imports

• TracerProvider setup

  from opentelemetry import trace
  from opentelemetry.sdk.trace import TracerProvider
  from opentelemetry.sdk.trace.export import BatchSpanProcessor
  from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
  from opentelemetry.sdk.resources import Resource
  
  # Configure provider with resource and exporter
  resource = Resource.create({'service.name': 'my-service'})
  provider = TracerProvider(resource=resource)
  
  exporter = OTLPSpanExporter(endpoint='http://localhost:4317')
  processor = BatchSpanProcessor(exporter)
  provider.add_span_processor(processor)
  
  # MUST register globally before any tracing
  trace.set_tracer_provider(provider)
  
  # Get tracer
  tracer = trace.get_tracer(__name__)
  
  # Use tracer
  with tracer.start_as_current_span('my-operation') as span:
      span.set_attribute('user.id', '42')
      # do work

  trace.get_tracer() returns a NoopTracer unless trace.set_tracer_provider() has been called with a real TracerProvider. No error is raised — spans are silently discarded.

Quickstart

OpenTelemetry Python — TracerProvider setup with ConsoleSpanExporter.

# pip install opentelemetry-api opentelemetry-sdk
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.sdk.resources import Resource

# Setup — do this once at app startup
resource = Resource.create({'service.name': 'my-service', 'service.version': '1.0.0'})
provider = TracerProvider(resource=resource)

# ConsoleSpanExporter for local dev — replace with OTLPSpanExporter in production
provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

# Register globally — MUST be before any trace.get_tracer() calls
trace.set_tracer_provider(provider)

# Get tracer
tracer = trace.get_tracer(__name__)

# Create spans
with tracer.start_as_current_span('main-operation') as span:
    span.set_attribute('env', 'production')

    with tracer.start_as_current_span('db-query') as child:
        child.set_attribute('db.system', 'postgresql')
        child.set_attribute('db.statement', 'SELECT * FROM users')
        # do DB work

# Flush remaining spans on shutdown
provider.shutdown()