PricingLoginStart free
FastAPI Backend Development Bootcamp · レッスン

OpenTelemetryによる分散トレーシング

FastAPIを自動計装し、下流のHTTP呼び出しやデータベース呼び出しにトレースコンテキストを伝播させます。

レッスン 2/413 ステップ

「OpenTelemetryによる分散トレーシング」はCoddyKit上の無料FastAPI Backend Development Bootcampレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはFastAPI Backend Development Bootcamp学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 FastAPI Backend Development Bootcampコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Distributed Tracing?

In a microservice or even a single-service backend that talks to other HTTP APIs and a database, a single user request fans out into many operations. When something is slow or fails, logs alone can't show you the causal chain across process boundaries.

Distributed tracing solves this by giving every request a shared trace_id and breaking the work into nested spans:

  • A trace = the whole journey of one request.
  • A span = one timed unit of work (an HTTP handler, a DB query, an outbound call).
  • Spans carry a parent_span_id, forming a tree.

OpenTelemetry (OTel) is the vendor-neutral standard and SDK we use to produce these traces from FastAPI and ship them to a backend like Jaeger, Tempo or an OTLP collector.

The OpenTelemetry Data Model

Before wiring anything up, understand the core objects you'll configure in code:

  • TracerProvider — the factory that creates tracers; you configure it once at startup.
  • Tracer — obtained from the provider, used to start spans.
  • Span — has a name, start/end time, attributes (key/value tags), events, and a status.
  • SpanProcessor — batches finished spans (use BatchSpanProcessor in production).
  • Exporter — serializes spans and sends them out (OTLP over gRPC/HTTP).
  • Context — the thread-/task-local carrier that holds the currently active span.

The flow is: TracerProvider → Tracer → Span → SpanProcessor → Exporter → backend.

Installing and Bootstrapping the SDK

For a FastAPI backend you install the SDK, the OTLP exporter, and the instrumentation packages:

  • opentelemetry-sdk, opentelemetry-api
  • opentelemetry-exporter-otlp
  • opentelemetry-instrumentation-fastapi, -httpx, -sqlalchemy

At startup you build a TracerProvider with a Resource that names your service, attach a BatchSpanProcessor wrapping an OTLP exporter, then register it globally. The service.name attribute is critical — it's how your tracing backend groups spans.

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)


def configure_tracing() -> None:
    resource = Resource.create({
        "service.name": "orders-api",
        "service.version": "1.4.0",
        "deployment.environment": "production",
    })
    provider = TracerProvider(resource=resource)
    exporter = OTLPSpanExporter(endpoint="http://otel-collector:4317")
    provider.add_span_processor(BatchSpanProcessor(exporter))
    trace.set_tracer_provider(provider)

Auto-Instrumenting FastAPI

The FastAPIInstrumentor wraps your app so every incoming request automatically becomes a server span. It reads the route, method, and status code, and — crucially — extracts the incoming trace context from request headers so this service's spans attach to the caller's trace.

Call configure_tracing() first, then instrument the app instance right after you create it. Order matters: the provider must be set globally before instrumentation reads it.

from fastapi import FastAPI
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

from .tracing import configure_tracing

configure_tracing()

app = FastAPI(title="orders-api")
FastAPIInstrumentor.instrument_app(app)


@app.get("/orders/{order_id}")
async def get_order(order_id: int):
    # This handler already runs inside an auto-created server span.
    return {"order_id": order_id, "status": "shipped"}

Trace Context Propagation: The W3C traceparent Header

The magic that links spans across services is context propagation. OpenTelemetry defaults to the W3C Trace Context standard, which uses a traceparent HTTP header:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

  • 00 — version
  • 4bf9...4736 — the 16-byte trace-id (shared across all services)
  • 00f0...02b7 — the parent span-id of the caller
  • 01 — trace flags (sampled bit)

On the way out, instrumented HTTP clients inject this header. On the way in, the server instrumentation extracts it. That's how a trace stays unbroken across the network.

Propagating Through Outbound HTTP Calls

When your FastAPI handler calls a downstream service, you must use an instrumented HTTP client so the traceparent header is injected automatically. With httpx, enable HTTPXClientInstrumentor once at startup.

Now every outbound request creates a client span that is a child of the current server span, and the downstream service continues the same trace.

import httpx
from fastapi import FastAPI
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

HTTPXClientInstrumentor().instrument()

app = FastAPI()


@app.get("/orders/{order_id}/full")
async def get_full_order(order_id: int):
    async with httpx.AsyncClient(base_url="http://payments") as client:
        # traceparent is injected automatically on this request.
        resp = await client.get(f"/charges/{order_id}")
    return {"order_id": order_id, "payment": resp.json()}

Propagating Through Database Calls

Database queries are often the slowest part of a request, so you want them as spans too. For SQLAlchemy, the SQLAlchemyInstrumentor creates a span per statement and records the SQL and DB system as attributes.

You must instrument the engine (pass engine=... for sync, or the sync engine behind an async engine). These DB spans become children of the active request span, so a slow query shows up nested under the handler that triggered it.

from sqlalchemy.ext.asyncio import create_async_engine
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

engine = create_async_engine("postgresql+asyncpg://app:secret@db/orders")

# For async engines, instrument the underlying sync engine.
SQLAlchemyInstrumentor().instrument(engine=engine.sync_engine)

# Every statement run through this engine now emits a DB span
# nested under the current request span automatically.

Creating Manual Spans for Business Logic

Auto-instrumentation covers I/O boundaries, but your own logic is invisible. Add manual spans around meaningful units of work to see where time goes. Get a tracer from the global provider and use it as a context manager.

Because the span is started inside the active request context, it automatically nests under the request span — no manual parent wiring needed.

from opentelemetry import trace

tracer = trace.get_tracer(__name__)


def price_order(items: list[dict]) -> float:
    with tracer.start_as_current_span("price_order") as span:
        span.set_attribute("order.item_count", len(items))
        subtotal = sum(i["price"] * i["qty"] for i in items)
        tax = round(subtotal * 0.20, 2)
        total = subtotal + tax
        span.set_attribute("order.total", total)
        return total

Enriching Spans with Attributes, Events and Status

A span becomes useful when it carries context. Use:

  • set_attribute(key, value) for searchable tags (user id, tenant, item count). Follow OTel semantic conventions where they exist.
  • add_event(name, attributes) for time-stamped markers (e.g. "cache_miss").
  • set_status(Status(StatusCode.ERROR)) and record_exception(exc) when something fails, so the span shows up red in your backend.

Never put secrets or full PII in attributes — traces are widely readable.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer(__name__)


def reserve_stock(sku: str, qty: int, available: int) -> None:
    with tracer.start_as_current_span("reserve_stock") as span:
        span.set_attribute("inventory.sku", sku)
        span.set_attribute("inventory.requested_qty", qty)
        if qty > available:
            span.add_event("stock_shortfall", {"available": available})
            exc = ValueError(f"Only {available} of {sku} in stock")
            span.record_exception(exc)
            span.set_status(Status(StatusCode.ERROR))
            raise exc
        span.set_status(Status(StatusCode.OK))

Sampling: Controlling Trace Volume

Tracing every request at full volume is expensive. Sampling decides which traces to keep. The recommended head-based sampler is ParentBasedTraceIdRatioBased:

  • If an incoming request already carries a sampling decision (the 01 flag in traceparent), it is respected — so a trace is kept or dropped consistently across every service.
  • For new root requests, it samples a fixed ratio (e.g. 10%).

This consistency is why parent-based sampling matters: you never want service A to keep a span while service B drops its child, leaving a broken trace.

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import (
    ParentBasedTraceIdRatioBased,
)

# Keep ~10% of root traces; honor upstream sampling decisions.
sampler = ParentBasedTraceIdRatioBased(rate=0.10)
provider = TracerProvider(sampler=sampler)

Correlating Logs with Traces

Traces and logs are most powerful together. Inject the current trace_id and span_id into every log line so you can jump from a log entry straight to the full trace.

You read the active span context from trace.get_current_span().get_span_context(). With the logging instrumentation enabled, OTel can also auto-inject these fields into the standard logging record.

import logging
from opentelemetry import trace

logger = logging.getLogger("orders")


def log_with_trace(message: str) -> None:
    ctx = trace.get_current_span().get_span_context()
    trace_id = format(ctx.trace_id, "032x")
    span_id = format(ctx.span_id, "016x")
    logger.info("%s", message, extra={
        "trace_id": trace_id,
        "span_id": span_id,
    })

Quick Check: Propagation Across Services

Service A (FastAPI) receives a request and calls Service B over HTTP. You want B's spans to appear under the same trace as A's. Which mechanism makes this work?

対話的なレッスンで答える

Recap

You can now instrument a FastAPI backend for distributed tracing end to end:

  • Bootstrap a TracerProvider with a Resource (set service.name), a BatchSpanProcessor, and an OTLP exporter.
  • Auto-instrument the app with FastAPIInstrumentor so every request is a server span that extracts incoming context.
  • Propagate through downstream HTTP (HTTPXClientInstrumentor) and the database (SQLAlchemyInstrumentor) — the W3C traceparent header keeps the trace unbroken.
  • Enrich with manual spans, attributes, events, status and recorded exceptions for your business logic.
  • Sample with ParentBasedTraceIdRatioBased for consistent, affordable traces, and correlate logs via the active trace_id/span_id.

The result: one click takes you from a slow request to the exact nested span — handler, HTTP call, or query — that caused it.

無料で開始

AI チューターと学ぶ FastAPI Backend Development Bootcamp — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース
21
レッスン
84
無料で学習を始めるコース全体を表示

よくある質問

「OpenTelemetryによる分散トレーシング」レッスンは無料ですか？

はい。「OpenTelemetryによる分散トレーシング」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、FastAPI Backend Development Bootcampコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 FastAPI Backend Development Bootcampコースには全4レッスンが含まれています。

「OpenTelemetryによる分散トレーシング」で何を学びますか？

FastAPIを自動計装し、下流のHTTP呼び出しやデータベース呼び出しにトレースコンテキストを伝播させます。 ブラウザで直接実行するハンズオンコードでFastAPI Backend Development Bootcampを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

FastAPI Backend Development Bootcampを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのFastAPI Backend Development Bootcampは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。

「OpenTelemetryによる分散トレーシング」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このFastAPI Backend Development Bootcampレッスンでコードを書いて実行できますか？

はい。すべてのFastAPI Backend Development Bootcampレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. 構造化JSONロギングと相関ID
  2. OpenTelemetryによる分散トレーシング
  3. PrometheusメトリクスとRED／USEダッシュボード
  4. SLOとエラーバジェットに基づくアラート
← FastAPI Backend Development Bootcampに戻る