Python WebAcademy Blog

FastAPIにOpenTelemetryが標準搭載。0.143では自動設定がオプトインに変わったニュースを初心者向けに解説

公開日: 2026-10-12 | 更新日: 2026-10-12

PythonのWebフレームワークFastAPIが、2026年9月29日の0.142.0でOpenTelemetryへの対応を標準で組み込みました。10月8日の0.143.0では、環境変数から送り先を自動設定する機能がオプトインに変わっています。テレメトリとは何か、何が記録されるのかを、実際に動かして取れた記録とともに初心者向けに整理します。

PythonのWebフレームワークFastAPIに、OpenTelemetryへの対応が標準で組み込まれました。2026年9月29日に公開された0.142.0での追加です。

さらに10月8日の0.143.0では、その設定の一部が、自分で有効にしたときだけ動くオプトイン方式に変わりました。短い間に2回動きがあったので、混乱している方もいるかもしれません。

そもそもOpenTelemetryって何だろう、という方も多いはずです。今回は、言葉の意味から、実際に何が記録されるのかまで順番に見ていきます。

まずは何が起きたのかを整理しよう¶

最初に、2つのリリースで変わったことを表にまとめます。内容は、FastAPIの公式リポジトリにあるリリースノートにもとづいています。

バージョン	公開日	変更
0.142.0	2026年9月29日	OpenTelemetryへの対応を標準で追加
0.142.3、0.142.4	2026年10月7日	テレメトリまわりの不具合修正
0.143.0	2026年10月8日	環境変数からの送り先の自動設定をオプトインに変更

0.143.0のリリースノートでは、この変更が互換性を壊す変更として扱われています。ただし、自分で送り先の設定をしているアプリは、何も変える必要はないと説明されています。

FastAPIそのものがまだよくわからない方は、先にこちらを読んでおくと話がつながります。【関連記事】PythonのFastAPIとは？

テレメトリとOpenTelemetryとは¶

FastAPIの公式ドキュメントでは、テレメトリを、アプリの動きについてのデータと説明しています。どれくらいアクセスがあるのか、どのリクエストが遅いのか、いつエラーが起きたのかを知るための材料です。

ドキュメントでは、テレメトリの代表的な種類として次の3つが挙げられています。

種類	中身	例
メトリクス	時間ごとにまとめられる測定値	応答時間、処理中のリクエスト数
トレース	1つのリクエストの中で行われた処理の記録	どの処理に何ミリ秒かかったか
ログ	時刻付きの出来事の記録	アプリの起動、処理の失敗

トレースの中の、時間を計った1つ1つの処理はスパンと呼ばれます。このあと実際に見るので、言葉だけ覚えておいてください。

OpenTelemetryは、こうしたデータを集めて、監視サービスに送るための標準とツールの集まりです。特定の会社の製品ではなく、共通の約束ごとなので、送り先のサービスを選ばずに使えるのが特長です。

0.142.0で何ができるようになったのか¶

ドキュメントによると、FastAPIは標準で、HTTPリクエストのトレース、メトリクス、ログに対応します。WebSocketの接続についても、トレースとログが取れます。

しかも、テレメトリを集めるために自分で特別なコードを書く必要はありません。fastapi[standard]でインストールすれば、送信に必要なパッケージも一緒に入ります。

何が記録されるのか¶

リクエストのトレースには、いくつかの処理のスパンが含まれます。ドキュメントには、依存関係の解決、関数の実行、レスポンスの変換、BackgroundTasksの各タスクが挙げられています。

扱われなかった例外は、リクエストのトレースと結びついたログとして記録されます。入力の検証に失敗したときも、ルートとエラーの件数が警告のログとして残ります。

実際にスパンを取り出してみた¶

では、どんな記録が取れるのか、実際に試してみましょう。ドキュメントの例をもとに、記録をメモリに貯めて表示する形に書き換えました。

from fastapi import FastAPI
from fastapi.testclient import TestClient
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

exporter = InMemorySpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))

app = FastAPI(telemetry={"tracer_provider": tracer_provider})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}


client = TestClient(app)
print(client.get("/items/1").json())

for span in exporter.get_finished_spans():
    ms = (span.end_time - span.start_time) / 1_000_000
    print(f"{span.name:<30} {ms:.2f} ms")

FastAPI 0.143.0を新しい仮想環境に入れ、手元のPython 3.11で実行した結果です。テストクライアントが出す警告の行は省いています。

{'item_id': 1}
fastapi.dependencies           0.08 ms
fastapi.endpoint               0.01 ms
fastapi.serialization          0.01 ms
GET /items/{item_id}           1.90 ms

1回のリクエストの中に、依存関係の解決、関数の実行、レスポンスの変換という3つのスパンが記録されています。最後の行が、リクエスト全体のスパンです。

アプリのコードにはテレメトリのための処理を何も書いていないのに、これだけの記録が取れました。どこで時間がかかっているかを調べる手がかりとして、とても便利です。

処理の遅いところを計測で見つける考え方は、cProfileの記事でも紹介しています。【関連記事】PythonのcProfileとは？

0.143.0で何が変わったのか¶

0.142.0では、OTELで始まる環境変数に送り先が書かれていると、FastAPIが自動で送信の仕組みを用意していました。0.143.0では、この自動設定が、自分で有効にしたときだけ動くようになりました。

リリースノートによると、これまでの動きを続けたい場合は、次のどちらかを設定します。

方法	書き方
環境変数で有効にする	`FASTAPI_OTEL_AUTO_CONFIGURE=true`
コードで有効にする	`FastAPI(telemetry={"auto_configure": True})`

ドキュメントによると、コードで指定した値は、環境変数の設定よりも優先されます。逆にFalseを指定すれば、環境変数で有効になっていても、そのアプリだけ自動設定を止められます。

なぜオプトインにしたのか¶

リリースノートには、変更の理由までは詳しく書かれていません。ただドキュメントには、ほかのライブラリがすでに同じ送り先へ送っている場合は、自動設定を切っておかないとテレメトリが重複する、という注意があります。

送り先の設定は、使う人がはっきり選んだときだけ動くほうが、思わぬ二重送信を防ぎやすいのは確かです。これは筆者の推測ですが、そうした安全側の判断なのでしょう。

環境変数の扱い方そのものは、こちらで解説しています。【関連記事】環境変数とは？PythonでAPIキーを安全に扱う

監視サービスへ送るときの設定¶

実際に監視サービスへ送るときは、ドキュメントの手順に沿って環境変数を3つ設定します。OTLPは、OpenTelemetryのデータを送るための通信の決まりごとです。

export FASTAPI_OTEL_AUTO_CONFIGURE=true
export OTEL_SERVICE_NAME=my-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

OTEL_SERVICE_NAMEは、監視サービスの画面でアプリを見分けるための名前です。ドキュメントによると、トレースは送り先のURLの/v1/traces、メトリクスは/v1/metrics、ログは/v1/logsへ送られます。

0.143.0からは、1行目のFASTAPI_OTEL_AUTO_CONFIGURE=trueがないと自動では送られない点が、0.142との大きな違いです。送り先が認証を求める場合は、OTEL_EXPORTER_OTLP_HEADERSも設定します。

記録する内容を選ぶ設定¶

FastAPIのtelemetryには、ほかにも何を記録するかを選ぶ設定があります。ドキュメントの表から、主なものを紹介します。

設定	役割	既定
tracing	リクエストのスパンを記録する	True
metrics	リクエストのメトリクスを記録する	True
logs	検証の失敗や扱われなかった例外を記録する	True
operation_spans	依存関係の解決などの細かなスパンを加える	True
exclude	指定した条件のリクエストを記録しない	None