Registry /
observability / opentelemetry-instrumentation-starlette
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.618s · 56.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 0.602s · 55MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StarletteInstrumentor
✓ from opentelemetry.instrumentation.starlette import StarletteInstrumentor
This quickstart demonstrates how to instrument a Starlette application with OpenTelemetry for tracing. It sets up a basic `TracerProvider` with an OTLP gRPC exporter and then applies the `StarletteInstrumentor` to the application. It's configured to use environment variables for service name and OTLP endpoint for flexibility.
import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
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.instrumentation.starlette import StarletteInstrumentor
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route
# Configure OpenTelemetry SDK
resource = Resource.create({
SERVICE_NAME: os.environ.get('OTEL_SERVICE_NAME', 'starlette-app')
})
tracer_provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317'),
insecure=True # Use secure=False for production with TLS
)
span_processor = BatchSpanProcessor(otlp_exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
# Define Starlette application
async def homepage(request):
with trace.get_current_span() as span:
span.set_attribute("custom_attribute", "hello from homepage")
return PlainTextResponse("Hello, world!")
async def user_detail(request):
user_id = request.path_params['user_id']
return PlainTextResponse(f"User ID: {user_id}")
routes = [
Route("/", homepage),
Route("/users/{user_id:int}", user_detail),
]
app = Starlette(routes=routes)
# Instrument the Starlette application
StarletteInstrumentor().instrument_app(app)
# To run: uvicorn your_app_file_name:app --port 8000
# Make sure an OTLP collector is running at localhost:4317 (or specified endpoint)
opentelemetry-instrument --version
Debug
Known issues
gotchaThe library `opentelemetry-instrumentation-starlette` is currently in beta (`0.62b0`). This means the API is subject to change without adhering to strict semantic versioning, and stability guarantees are limited. Production usage should monitor release notes for breaking changes.fixReview release notes for each new version. Pin exact versions for stability in production environments.
affects: All versions with 'b' suffix (e.g., 0.x.ybZ)
breakingThe OpenTelemetry SDK (including `TracerProvider` and exporters) *must* be initialized and configured before any instrumented library (like Starlette) is imported or used. Failing to do so can result in instrumentation hooks not being applied, leading to no telemetry data being collected.fixEnsure OpenTelemetry SDK setup code runs at the earliest possible point in your application's lifecycle, typically at the top of your main application file or in a dedicated setup module that is imported first. For auto-instrumentation via `opentelemetry-instrument`, ensure the command is used correctly.
affects: All versions
gotchaWhen running Starlette applications with pre-forking ASGI servers like Gunicorn (especially with multiple workers), OpenTelemetry's automatic metrics generation may be unreliable or broken. This is due to Python's forking model and how background threads (e.g., in `PeriodicExportingMetricReader`) interact with child processes.fixConsider using `uvicorn` with a single worker, or `gunicorn` with `uvicorn.workers.UvicornWorker` and `OTEL_PYTHON_AUTO_INSTRUMENTATION_ENABLE_FORK_PATCH=true` (if available and tested) or use programmatic instrumentation to explicitly initialize the SDK in each worker process after forking. Consult OpenTelemetry Python documentation on pre-fork server issues.
affects: All versions with multi-worker Gunicorn configurations
gotchaThe order of OpenTelemetry instrumentation relative to other Starlette middleware can be crucial. If other middleware modifies the ASGI scope in a way that interferes with the instrumentation, or if instrumentation needs to capture attributes set by other middleware, placement matters.fixGenerally, place `StarletteInstrumentor().instrument_app(app)` early in your application's setup, often directly after the `Starlette` app instance is created. If using manual middleware, ensure `OpenTelemetryMiddleware` (from `opentelemetry-instrumentation-asgi`) is positioned appropriately in your middleware stack.
affects: All versions
deprecatedOlder versions of `opentelemetry-instrumentation-starlette` (prior to `1.34.0/0.55b0`) had known issues with capturing custom headers correctly, particularly with Starlette versions >= 0.15.0. While fixed in newer versions, using outdated instrumentation might lead to missing header attributes.fixEnsure you are using `opentelemetry-instrumentation-starlette` version `0.55b0` or newer to benefit from fixes related to Starlette version compatibility and header capture.
affects: < 0.55b0 (OpenTelemetry Python Contrib version nomenclature)
gotchaTo prevent storing sensitive data or to reduce noise, certain URLs or HTTP headers should be excluded from tracing. If not configured, sensitive paths (e.g., health checks, client secrets) might generate unnecessary spans or expose data.fixUse environment variables `OTEL_PYTHON_STARLETTE_EXCLUDED_URLS` (Starlette-specific) or `OTEL_PYTHON_EXCLUDED_URLS` (global) with comma-delimited regex patterns to exclude URLs. Similarly, use `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` to sanitize header values.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
starletterequiredCore web framework being instrumented.
opentelemetry-apirequiredOpenTelemetry API for Python.
opentelemetry-sdkrequiredOpenTelemetry SDK for Python.
opentelemetry-instrumentationrequiredBase OpenTelemetry instrumentation utilities.
opentelemetry-semantic-conventionsrequiredStandardized semantic conventions for telemetry.
opentelemetry-util-httprequiredHTTP utilities for instrumentation.
asgirefrequiredASGI (Asynchronous Server Gateway Interface) utilities, a core dependency for Starlette.