otel-fastapi-style

OTel FastAPI スタイル

ネイティブの FastAPI インストルメンテーションを使用してください。スパンを作成するためだけに、リクエスト処理を手動のミドルウェアに置き換えないでください。

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

def init_observability(app: FastAPI) -> bool:
    ...
    FastAPIInstrumentor.instrument_app(app)
    return True

FastAPIInstrumentor.instrument_app(app) は、残りのオブザーバビリティ設定と一緒に維持し、ブートストラップの動作を把握しやすくしてください。サインアップがまだ進行中で生成されたトークンが未登録の場合でも、プロバイダーを初期化して問題ありません。ブラウザのフローが完了するまでは、取り込み時にエクスポートが拒否されることがあります。

エントリーポイント

ユーザートラフィックを処理する前に初期化してください。

app = FastAPI(title="Mugline API")
init_observability(app)

有界な処理

自動インストルメンテーションされた HTTP スパンでは捕捉できないヘルパーには、モジュールスコープの OTel オブジェクトとデコレーターを使用してください。

tracer = trace.get_tracer("mugline.api")
meter = metrics.get_meter("mugline.api")

@tracer.start_as_current_span("mug.recommend")
async def recommend_mug(*, tenant_id: str, preference: str) -> dict[str, str]:
    span = trace.get_current_span()
    span.set_attribute("tenant.id", tenant_id)
    ...

ログ

OTLP に転送する標準ライブラリのログでは、以下をすべて設定してください。

• LoggerProvider
• set_logger_provider(logger_provider)
• OTLPLogExporter
• LoggingHandler
• LoggingInstrumentor().instrument(...)

LLM 呼び出し

LLM のルートでは、トークンを計測する必要があります。

• llm.tokens.input
• llm.tokens.output

プロバイダーのインストルメンテーションでトークン使用量を捕捉できない場合に限り、テナント、プロバイダー、モデル、ユースケース、呼び出し元、結果を明示的なトークンカウンターのタグとして設定してください。アプリ側で LLM のコストメトリクスや料金表を追加しないでください。Superlog は、プロバイダー、モデル、トークンのデータからコストを一元的に推定します。