OpenTelemetry FastAPI Instrumentation

Warnings

• gotcha The `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.
  Fix: Always check the `CHANGELOG.md` in the `opentelemetry-python-contrib` repository before upgrading to new beta versions. Pin your dependency versions to avoid unexpected changes.
• breaking Support 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.
  Fix: Ensure your project uses FastAPI version 0.92.0 or newer. Upgrade FastAPI if necessary (`pip install "fastapi>=0.92.0"`).
• gotcha When 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.
  Fix: Initialize 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.
• gotcha The 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.
  Fix: Ensure `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.
• gotcha OpenTelemetry 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.
  Fix: Regularly 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.

Install

• pip install opentelemetry-instrumentation-fastapi opentelemetry-exporter-otlp Install core instrumentation and OTLP exporter

Imports

• FastAPIInstrumentor

  from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

Quickstart

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