トレースを計装する

🐱 この章の目次

SDK のセットアップ

トレースの計装には、まず必要なパッケージをインストールします。

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

TracerProvider は、Tracer を生成し、Span の処理パイプラインを管理する中心的なコンポーネントです。 SpanProcessor が Span のライフサイクルを制御し、Exporter がデータの送信先を決定します。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4317"))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

BatchSpanProcessor は Span をバッファリングしてバッチ送信するため、本番環境に適しています。開発時はコンソールへ出力する SimpleSpanProcessor + ConsoleSpanExporter の組み合わせが便利です。

Span の作成と属性

Span は、ひとつの処理単位を表すトレースの構成要素です。属性を付与することで、検索やフィルタリングに使える構造化された情報を付加できます。

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("fetch-user") as span:
    span.set_attribute("user.id", user_id)
    span.set_attribute("db.system", "postgresql")
    user = db.get_user(user_id)

例外が発生した場合は record_exception で Span にエラー情報を記録します。ステータスを ERROR に設定することで、バックエンド側でエラー Span を識別可能になります。

from opentelemetry.trace import StatusCode

with tracer.start_as_current_span("payment") as span:
    try:
        process_payment(order)
    except Exception as e:
        span.record_exception(e)
        span.set_status(StatusCode.ERROR, str(e))
        raise

FastAPI の自動計装

FastAPI アプリケーションには専用の自動計装パッケージが用意されています。

pip install opentelemetry-instrumentation-fastapi

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

app = FastAPI()
FastAPIInstrumentor.instrument_app(app)

これだけで、全リクエストに対して Span が自動生成され、HTTP メソッド・パス・ステータスコードが属性として記録されます。内部のビジネスロジックには手動計装で子 Span を追加し、ボトルネックを可視化しましょう。