Registry /
observability / opentelemetry-instrumentation-fastapi
OpenTelemetry FastAPI Instrumentation provides automatic and manual instrumentation for FastAPI web frameworks. It allows for comprehensive application performance monitoring (APM), distributed tracing, and observability by collecting traces and metrics from HTTP requests, database queries, and external API calls with minimal code changes. The library is currently in beta (version 0.61b0) and is part of the broader `opentelemetry-python-contrib` project, which sees frequent updates across its various instrumentations.
Install & Compatibility
Where this runs
tested against v0.63b1 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastAPIInstrumentor
✓ from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
This quickstart demonstrates how to set up OpenTelemetry instrumentation for a FastAPI application. It initializes a `TracerProvider` with an `OTLPSpanExporter` to send traces to an OTLP-compatible backend. The `FastAPIInstrumentor.instrument_app(app)` call automatically creates spans for incoming HTTP requests. The OpenTelemetry setup is integrated using FastAPI's `lifespan` events for proper initialization and shutdown, especially crucial for multi-process environments like uvicorn with multiple workers. Make sure an OTLP collector is running at the specified endpoint.
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from opentelemetry import trace
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
# Configure OpenTelemetry SDK
# It is recommended to initialize OpenTelemetry within FastAPI's lifespan events
# when using multi-process servers (e.g., uvicorn --workers > 1 or gunicorn).
# For simple single-process development, top-level initialization is sufficient.
def setup_tracing():
resource = Resource.create(attributes={
"service.name": os.environ.get("OTEL_SERVICE_NAME", "my-fastapi-app")
})
tracer_provider = TracerProvider(resource=resource)
# Use OTLP HTTP exporter for traces
# OTLP endpoint can be configured via environment variable OTEL_EXPORTER_OTLP_ENDPOINT
# Default is http://localhost:4318/v1/traces for HTTP
otlp_exporter = OTLPSpanExporter(
endpoint=os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318/v1/traces")
)
span_processor = BatchSpanProcessor(otlp_exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
print("OpenTelemetry tracing initialized.")
@asynccontextmanager
async def lifespan(app: FastAPI):
# Startup logic: Initialize OpenTelemetry
setup_tracing()
FastAPIInstrumentor.instrument_app(app)
yield
# Shutdown logic: Flush and shutdown exporter
provider = trace.get_tracer_provider()
if hasattr(provider, 'shutdown'):
provider.shutdown()
print("OpenTelemetry tracing shutdown.")
# Initialize FastAPI app with lifespan events
app = FastAPI(lifespan=lifespan)
@app.get("/hello")
async def read_root():
return {"message": "Hello, World!"}
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id, "message": "Item fetched"}
# To run this application:
# 1. Save it as main.py
# 2. Run from your terminal:
# OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces" OTEL_SERVICE_NAME="my-fastapi-app" uvicorn main:app --port 8000 --reload --lifespan on
# Note: For production, omit --reload and manage workers via gunicorn post_fork hooks if using multiple workers.
# 3. Access in browser: http://localhost:8000/hello or http://localhost:8000/items/123
Debug
Known issues
gotchaThe `opentelemetry-instrumentation-fastapi` library is currently in beta (indicated by the `b0` suffix in the version). This means its API and behavior might be subject to breaking changes in future releases before reaching a stable `1.0.0` version.fixAlways check the `CHANGELOG.md` in the `opentelemetry-python-contrib` repository before upgrading to new beta versions. Pin your dependency versions to avoid unexpected changes.
affects: 0.x.xb0
breakingSupport for FastAPI versions earlier than 0.92 has been dropped. Using older FastAPI versions will lead to `FastAPIInstrumentor` failing to properly instrument your application or causing unexpected errors.fixEnsure your project uses FastAPI version 0.92.0 or newer. Upgrade FastAPI if necessary (`pip install "fastapi>=0.92.0"`).
affects: <0.60b0
gotchaWhen running FastAPI with `uvicorn --reload` (development mode) or with multiple worker processes (e.g., `uvicorn --workers N` or `gunicorn` with `uvicorn.workers.UvicornWorker`), OpenTelemetry SDK initialization can cause issues due to Python's process forking model. Background threads and shared resources from the parent process are not correctly replicated in child workers.fixInitialize OpenTelemetry SDK and `FastAPIInstrumentor.instrument_app()` within FastAPI's `lifespan` event handlers or within Gunicorn's `post_fork` hook. This ensures each worker process has its own isolated and correctly initialized OpenTelemetry components. Avoid `uvicorn --reload` when reliable tracing is required.
affects: All versions
gotchaThe order of instrumentation is critical. `FastAPIInstrumentor.instrument_app(app)` must be called after the FastAPI application instance (`app`) has been created but before the application starts processing requests. Improper ordering can lead to incomplete tracing or errors.fixEnsure `FastAPIInstrumentor.instrument_app(app)` is called early in your application's startup, typically immediately after `app = FastAPI()` or within a `lifespan` event. If using `opentelemetry-bootstrap`, ensure `initialize()` is called before importing FastAPI.
affects: All versions
gotchaOpenTelemetry semantic conventions, which define naming for attributes and spans, can evolve. For example, `aws.region` was changed to `cloud.region`. This can affect how your telemetry data is displayed in older or un-updated observability backends.fixRegularly consult the official OpenTelemetry semantic conventions for HTTP and other relevant signals. Update your observability backend to the latest versions to ensure proper interpretation of attributes. If using custom parsers, adjust them accordingly.
affects: All versions (due to evolving standards)
breakingThe `opentelemetry-instrumentation-fastapi` library requires `fastapi` as a peer dependency. This means `fastapi` must be explicitly installed in your project environment for the instrumentation to function. A `ModuleNotFoundError: No module named 'fastapi'` indicates that the `fastapi` package is missing.fixEnsure `fastapi` is included in your project's dependencies and installed (e.g., `pip install fastapi`).
affects: All versions
breakingThe `fastapi` package must be installed for `opentelemetry-instrumentation-fastapi` to function. This error occurs when FastAPI is not found in the Python environment.fixEnsure FastAPI is installed in your project's environment using `pip install fastapi` (or `pip install "fastapi[all]"` for full features). If using a virtual environment or Docker, verify it's correctly activated/configured.
affects: All versions
Audit
Dependencies
fastapirequiredThe web framework being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-instrumentation-asgirequiredFastAPI is built on the ASGI specification, and this instrumentation builds upon the base ASGI instrumentation.
opentelemetry-exporter-otlpoptionalCommon exporter for sending telemetry data to an OTLP-compatible backend (e.g., Jaeger, Tempo, OpenObserve).