Add OpenTelemetry tracing to FastAPI

Approach

Install the OpenTelemetry SDK and instrumentations for FastAPI, SQLAlchemy and httpx, configure an OTLP exporter via environment variables, and add manual spans around important business operations. Exclude health checks, and use sampling in production.

Solution

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio

provider = TracerProvider(resource=Resource.create({"service.name": "orders-api"}),
                          sampler=ParentBasedTraceIdRatio(0.1))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))   # OTEL_EXPORTER_OTLP_ENDPOINT
trace.set_tracer_provider(provider)

FastAPIInstrumentor.instrument_app(app, excluded_urls="healthz,readyz")
SQLAlchemyInstrumentor().instrument(engine=engine.sync_engine)
HTTPXClientInstrumentor().instrument()

tracer = trace.get_tracer("orders")


async def checkout(order_id: int):
    with tracer.start_as_current_span("checkout") as span:
        span.set_attribute("order.id", order_id)
        ...

# Or zero-code instrumentation:
pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install
OTEL_SERVICE_NAME=orders-api opentelemetry-instrument fastapi run app/main.py

Pitfalls

• 100% sampling at high traffic.
• Instrumenting after the app/engine is already serving requests.
• High-cardinality span names (use route templates).

Variations

• Logfire (Pydantic) or vendor agents built on OpenTelemetry.

Further reading: OpenTelemetry: Python zero-code