FastAPI Backend Development Bootcamp · 강의

OpenTelemetry를 활용한 분산 추적

FastAPI를 자동으로 계측하고 하위 HTTP 및 데이터베이스 호출에 추적 컨텍스트를 전파합니다.

OpenTelemetry를 활용한 분산 추적은(는) CoddyKit의 무료 FastAPI Backend Development Bootcamp 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 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.

자주 묻는 질문

“OpenTelemetry를 활용한 분산 추적” 강의는 무료인가요?

네 — “OpenTelemetry를 활용한 분산 추적” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 FastAPI Backend Development Bootcamp 강의 전체를 잠금 해제할 수 있습니다. FastAPI Backend Development Bootcamp 강의에는 총 4개의 강의가 포함되어 있습니다.

“OpenTelemetry를 활용한 분산 추적”에서 뭘 배우나요?

FastAPI를 자동으로 계측하고 하위 HTTP 및 데이터베이스 호출에 추적 컨텍스트를 전파합니다. 브라우저에서 직접 실행하는 실습 코드로 FastAPI Backend Development Bootcamp을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

FastAPI Backend Development Bootcamp을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 FastAPI Backend Development Bootcamp은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“OpenTelemetry를 활용한 분산 추적” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 FastAPI Backend Development Bootcamp 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 FastAPI Backend Development Bootcamp 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← FastAPI Backend Development Bootcamp(으)로 돌아가기