OpenTelemetry Python SDK

1.40.0 verified Tue May 12 auth: no python install: verified quickstart: verified

The OpenTelemetry Python SDK provides APIs and implementations for collecting, processing, and exporting telemetry data such as traces and metrics. Current version: 1.40.0, released on March 4, 2026. The SDK follows a regular release cadence, with minor versions introducing new features and patch versions addressing bug fixes and improvements.

pip install opentelemetry-sdk

Common errors

error ModuleNotFoundError: No module named 'opentelemetry.instrumentation' ↓

cause This error occurs when an instrumentation package or a required OpenTelemetry package is not installed, or there's a mismatch in Python environments where packages are installed versus where the application runs, or due to namespace package conflicts.

fix

Ensure all necessary OpenTelemetry packages, especially specific instrumentations and exporters (e.g., opentelemetry-instrumentation-flask, opentelemetry-exporter-otlp-proto-grpc), are installed in the correct Python environment, often using pip install opentelemetry-distro opentelemetry-sdk followed by opentelemetry-bootstrap -a install for auto-instrumentation.

error Exporter Failed: connection refused ↓

cause This typically indicates that the OpenTelemetry Collector or your observability backend is not running, is inaccessible, or is listening on a different port than configured in your application's exporter settings. It can also be a network issue, an incorrect endpoint URL, or an authentication failure.

fix

Verify that the OpenTelemetry Collector or backend is running and accessible from your application's host and port (e.g., localhost:4317 for gRPC or localhost:4318 for HTTP). Check network connectivity, firewall rules, and ensure the exporter endpoint URL in your application configuration is correct.

error OpenTelemetry traces/spans/metrics not appearing (silent failure) ↓

cause This often happens when the OpenTelemetry SDK components (like the TracerProvider or MeterProvider) are initialized too late in the application lifecycle, especially in multi-process environments like Gunicorn or when using auto-instrumentation, causing early telemetry data to be dropped by 'no-op' providers or context to be lost across threads or forks.

fix

Ensure the OpenTelemetry SDK is initialized and the global providers are registered as early as possible in your application's startup, ideally before any other modules that might generate telemetry are imported or before worker processes are forked (e.g., using Gunicorn's post_worker_init hook). Use force_flush() for short-lived processes.

error WARNING: Invalid type NoneType for attribute value. ↓

cause OpenTelemetry attributes generally do not support `None` as a value type. This warning appears when a `None` value is passed as an attribute to a span, log, or metric, leading to the attribute being dropped or ignored.

fix

Ensure that all attribute values passed to OpenTelemetry spans, logs, or metrics are of valid types (strings, numbers, booleans, or arrays of these types). Implement checks to prevent None values from being passed, perhaps by providing a default value or omitting the attribute if its value is None.

Warnings

breaking In version 1.40.0, the 'LoggingHandler' has been deprecated in favor of 'opentelemetry-instrumentation-logging'. ↓

fix Install 'opentelemetry-instrumentation-logging' and update your code to use the new handler.

breaking The 'start_span' and 'start_as_current_span' methods in 'NoOpTracer' no longer return 'INVALID_SPAN' when a valid span context is present. ↓

fix Ensure your code handles the new behavior appropriately.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.30s 22.1M

3.10 slim (glibc) - - 0.20s 23M

3.11 alpine (musl) - - 0.49s 24.4M

3.11 slim (glibc) - - 0.37s 25M

3.12 alpine (musl) - - 0.67s 16.1M

3.12 slim (glibc) - - 0.59s 17M

3.13 alpine (musl) - - 0.35s 15.8M

3.13 slim (glibc) - - 0.34s 16M

3.9 alpine (musl) - - 0.29s 21.6M

3.9 slim (glibc) - - 0.26s 22M

Imports

TracerProvider
```
from opentelemetry.sdk.trace import TracerProvider
```
Ensure correct import path to access TracerProvider.
ConsoleSpanExporter
```
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
```
Ensure correct import path to access ConsoleSpanExporter.

Quickstart verified last tested: 2026-04-23

A simple example demonstrating how to set up tracing with the OpenTelemetry Python SDK.

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Set up the tracer provider
trace.set_tracer_provider(TracerProvider())

# Set up the exporter
console_exporter = ConsoleSpanExporter()
span_processor = BatchSpanProcessor(console_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

# Get a tracer
tracer = trace.get_tracer(__name__)

# Create a span
with tracer.start_as_current_span("example-span"):
    print("Hello, OpenTelemetry!")