API可観測性：概要と実現方法

APIオブザーバビリティとは、APIが発するテレメトリー（メトリクス、ログ、トレース）を調べることで、APIがなぜそのように動作するのかを理解する能力のことです。これは、固定されたダッシュボードを監視する以上のものです。適切に計装されたAPIは、すでに生成しているデータだけを使って、内部状態について、予期しなかったものも含め、新たな質問を投げかけることを可能にします。

button

APIオブザーバビリティが実際に意味するもの

この用語は、制御理論に由来します。制御理論では、システムの外部出力からその内部状態を推測できる場合、そのシステムは「オブザーバブルである（可観測である）」とされます。ソフトウェアに適用すると、APIは、その出力（テレメトリー）によって、新しいログ行を追加するためのコードをデプロイすることなく、あらゆる動作を診断するのに十分な情報を提供するときにオブザーバブルであると言えます。

この最後の部分が重要です。オブザーバビリティがあれば、顧客が午前2時に特定の地域で特定のAPIバージョンを使用しているユーザーに対して、チェックアウトリクエストが遅いと報告した場合、すでに収集しているデータから「なぜ」を答えることができるはずです。予測していなかった障害モードを調査するのに十分なほど豊富に計装されているのです。これは、あらかじめ尋ねることが分かっていた質問にしか答えない稼働時間チェックとは異なる目標です。

オブザーバビリティ vs モニタリング

人々はこれらの言葉を区別せずに使いますが、これらは異なる事柄を表しています。

モニタリングは、既知のシグナルを監視し、しきい値を超えたときにアラートを発します。追跡すべきもの（エラー率、CPU、p99レイテンシ）や、何が「悪い」と見なされるかを事前に決定します。モニタリングは「壊れると予想していたものが壊れているか？」という問いに答えます。

オブザーバビリティはシステムの特性であり、そのテレメトリーがいかに内部状態について任意の質問を可能にするかを示します。「これ」がダッシュボードを構築したことのないものであっても、「なぜこれがこのように動作しているのか？」という問いに答えます。

簡単に言えば、モニタリングは何か問題があることを知らせます。オブザーバビリティは、その理由を見つけるのに役立ちます。両方が必要です。モニタリングはアラートを提供し、オブザーバビリティはアラートから根本原因への道筋を提供します。アラートに関する詳細な解説が必要な場合は、当社のAPIモニタリングガイドで詳しく説明しています。

以下に、その違いを表で示します。

側面	モニタリング	オブザーバビリティ
回答される質問	既知のシグナルが範囲外か？	なぜシステムはこのように動作するのか？
定義されるタイミング	事前（事前定義されたチェック）	調査時（アドホックなクエリ）
最適な用途	既知の障害モード、SLO違反	新規の、予期せぬ問題
出力	アラート、ステータスダッシュボード	高カーディナリティの、クエリ可能なテレメトリー

3つの柱：メトリクス、ログ、トレース

オブザーバビリティは、しばしば3つの柱と呼ばれる3種類のテレメトリーに基づいています。ベンダーニュートラルな標準であるOpenTelemetryは、これらをテレメトリーの「シグナル」として形式化しています。OpenTelemetryは現在、トレース、メトリクス、ログ、バゲージをサポートしており、イベントとプロファイルが開発中です。古典的な3つの柱は、最初の3つのシグナルに対応します。

メトリクス

メトリクスは、時間経過とともに集計された数値測定値です。APIにとって最も重要なのは、リクエストレート、エラーレート、およびレイテンシ分布です。レイテンシは平均値だけでなく、パーセンタイル（p95およびp99）として報告してください。平均値では、実際のユーザーが感じる「遅い部分（slow tail）」が隠れてしまいます。

メトリクスはストレージコストが安く、クエリが高速であるため、ダッシュボードやアラートに最適です。その弱点はカーディナリティが低いことです。p99レイテンシが急上昇したことはわかりますが、どのリクエストが原因であるかはわかりません。

ログ

ログは、個別のイベントのタイムスタンプ付き記録です。構造化ログは、一貫性のあるフィールドを持つJSONとして出力され、フィルタリングや集計が可能であるため、自由形式のテキスト行よりもはるかに有用です。

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

trace_idフィールドに注目してください。このIDがログ行とより広範なリクエストフローをリンクさせ、これが3つ目の柱につながります。

トレース

分散トレースは、1つのリクエストがサービス間を移動する経路を追跡します。各ホップはスパンとなり、スパンはトレースIDを共有することで、完全なパスを再構築し、どこで時間が費やされたかを確認できます。リクエストがゲートウェイ、認証サービス、そして3つのマイクロサービスを通過する場合、どのホップが4秒を追加したかをトレースが示します。

トレースは、マイクロサービスのデバッグを実用的にするものです。これがないと、チェーン内のどのサービスが遅いのかを推測するしかありません。

3つの柱は連携して機能します。メトリックアラートがスパイクを検知します。トレースが遅いサービスを特定します。そのサービスからのログをトレースIDでフィルタリングすることで、何が起こったかを正確に知ることができます。

REDメソッドとゴールデンシグナル

すべてを追跡する必要はありません。REDメソッドは、リクエスト駆動型サービスのための集中的な出発点を提供します。Tom Wilkieが2015年にWeaveworksに在籍中に導入したもので、Googleの4つのゴールデンシグナルから派生しています。

REDは以下を表します。

Rate (レート): APIが処理する1秒あたりのリクエスト数。
Errors (エラー): 5xx応答や予期せぬ4xx応答など、失敗したリクエストの数または割合。
Duration (期間): リクエストのレイテンシ分布（p95およびp99として報告）。

Rate     = 1秒あたりのリクエスト数
Errors   = 5xx応答（および予期せぬ4xx応答）の割合
Duration = レイテンシ分布、p95およびp99（平均だけでなく）を報告

REDはリクエスト中心であり、API、ゲートウェイ、サービスメッシュによく適しています。その対義語であるUSE（Utilization, Saturation, Errors）は、CPUやディスクなどのインフラストラクチャリソースを対象とします。APIの場合、REDから始め、その下にあるホストにはUSEを追加します。

SLIとSLO：シグナルを目標に変える

オブザーバビリティデータは、それに目標を設定することで実用的なものになります。Google SREの書籍では、ここで2つの用語を定義しています。

サービスレベル指標（SLI）は、サービスの1つの側面を定量的に測定したものです。一般的なSLIには、リクエストレイテンシ、エラー率（失敗したすべてのリクエストの割合）、1秒あたりのリクエスト数でのスループットなどがあります。これらはREDと明確に一致します。

サービスレベル目標（SLO）は、SLIの目標値または範囲です。例えば、「28日間の期間にわたるリクエストの99.9パーセントは300ミリ秒未満で完了する」といったものです。SLOは、いつAPIが十分に健全であるか、そしていつ機能開発ではなく信頼性にエンジニアリング時間を費やすべきかをあなたとあなたのチームに伝えます。

SLIとSLOは、メトリクスに意味を与えます。これらがないと、レイテンシグラフはただの波線ですが、これらがあれば、測定可能な契約となります。

ツール：OpenTelemetryとバックエンド

オブザーバビリティツールは、テレメトリーをどのように生成するか、そしてどこに送信するかという2つの層に分けられます。

生成に関しては、OpenTelemetryが学ぶ価値のある標準です。これはCloud Native Computing Foundation (CNCF) プロジェクトであり、OpenTracingとOpenCensusを統合して形成されました。ベンダーやツールに依存しないため、幅広いバックエンドと連携します。その核となる原則は、ベンダーロックインなしに、生成したデータを自分で所有するというものです。API、言語SDK、セマンティック規約、OTLPワイヤプロトコル、自動計測、およびOpenTelemetry Collectorを提供します。

ストレージと分析については、いくつかの選択肢があります。PrometheusとGrafanaの組み合わせは、メトリクスとダッシュボードのための一般的なオープンソーススタックです。DatadogやHoneycombのような商用プラットフォームは、トレース、メトリクス、ログを取り込み、高カーディナリティのクエリを提供します。Datadogを使用している場合、当社のDatadog APIのウォークスルーでは、プログラムでデータをプッシュおよびプルする方法を示しています。

OpenTelemetryの目的は、一度計装すれば、再計装することなくバックエンドを切り替えられることです。この移植性が、早期に採用すべき主な理由です。

テストと合成チェックの位置づけ

オブザーバビリティは本番環境だけの懸念事項ではありません。最も有用なシグナルの一部は、デプロイメント前とデプロイメント後の両方で意図的に実行するテストから得られます。

シフトレフト：コントラクトテストとCI実行

コードがデプロイされる前に、コントラクトテストはAPIが仕様と一致していることを検証します。これらをCIで実行することで、破壊的な変更がユーザーに到達する前に捕捉できます。すべてのCIテスト実行はシグナルであり、コミット、環境、タイムスタンプに紐付けられた合格または不合格です。この履歴は、リリース品質に関するオブザーバビリティデータとなります。

Apidog CLIは、パイプラインでテストシナリオを実行します。Node.jsで構築されており、Node v16以降が必要です。

npm install -g apidog-cli
# verify the install
node -v && apidog -v

環境に対してテストシナリオを実行します。環境フラグは必須であり、トークンを明示的に渡します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

ここで、-tはテストシナリオID、-eは環境ID、-rはレポート形式（cli、html、json、junit）を設定します。デフォルトのレポーターはcliです。CSVまたはJSONファイルからシナリオを駆動するには、-d ./data.csvを追加します（-d、または--iteration-dataフラグはファイルパスを受け取ります）。レポートの概要をApidogクラウドにプッシュすることもできます。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

コピーして適応できる完全なパイプラインについては、当社のCI/CDガイド向けApidog CLI、またはすべてのフラグの完全なCLIリファレンスを参照してください。

本番環境での合成モニタリング

合成モニタリングは、ライブAPIに対して、ユーザーがアクセスするのと同じように、外部からスクリプト化されたリクエストをスケジュールに基づいて実行します。これにより、実際のトラフィックが問題を発見する前に問題を捕捉し、レイテンシと可用性のデータポイントを継続的に提供します。基本的なAPIヘルスチェックが最もシンプルな形式です。本格的な合成モニタリングは、ログイン後にチェックアウトするような多段階のフローにまで拡張されます。

これらのチェックは、それ自体がオブザーバビリティのシグナルです。午前2時に4秒の持続時間で失敗した合成実行は、トレースとログにフィードしたいイベントのまさにその種類です。専用ツールの調査については、合成テストツールのまとめを、本番環境モニタリングプラットフォームについては、APIモニタリングツールのリストを参照してください。

Apidogスケジュールタスクによるリアルなシグナル生成

Apidogは、スケジュールタスクを通じて定期的な合成シグナルを生成できます。この機能は、設定されたテストシナリオを自動的に指定された時間に実行し、結果をキャプチャし、スケジュールされた回帰テストをサポートします。これは「テスト」モジュール内の「スケジュールタスク」で見つけることができます。

これに頼る前に知っておくべき点がいくつかあります。スケジュールタスクは現在ベータ版であるため、長期安定した機能というよりも、進化中のものとして扱ってください。また、設定されたセルフホスト型Runnerが必要です。「Runs On」オプションには現在セルフホスト型Runnerがリストされており、Apidog Cloudは近日中に利用可能になると記載されています。したがって、完全にクラウドホスト型のスケジュールされたチェックはまだありません。

設定する際には、以下を選択します。

テストシナリオ: 実行する1つまたは複数のシナリオ。
実行モード: 毎週日曜日午後11時、または6時間ごとなど、実行タイミング。
通知: 各実行後、または失敗時のみアラートを出すか。

実行回数はサブスクリプションプランによって異なります。実践的な構築については、当社のApidogスケジュールタスクのウォークスルーを参照してください。

ここでの価値は、ループを閉じることです。APIを1か所で設計しテストした後、それらの同じシナリオを定期的に実行することで、パス/フェイルとレイテンシのシグナルを継続的に生成し、それに基づいて行動できるようになります。Apidogを無料でお試しください（クレジットカード不要）。既存のテストシナリオを定期的なシグナルに変えましょう。

オブザーバブルなAPIへの実践的な道筋

ゼロから始める場合は、この順序で作業を進めてください。

構造化されたログを生成する: すべてのリクエストで、一貫したスキーマとトレースIDを持つログを出力します。
OpenTelemetryで計装する: トレース、メトリクス、ログがコンテキストを共有し、バックエンド間で移植可能になるようにします。
REDメトリクスを追跡する: レート、エラー、期間（p95およびp99）を追跡し、ダッシュボードに表示します。
SLIとSLOを定義する: メトリクスが単なる傾向だけでなく、目標を持つようにします。
CIにコントラクトテストを追加する: リリース前に破壊的な変更を捕捉します。
合成チェックを実行する: 例えばApidogのスケジュールタスクを使用して、本番環境に対して定期的に合成チェックを実行します。

これらすべてを一度に行う必要はありません。ステップ1の「トレースID付き構造化ログ」だけでも、フラットなテキストログよりもはるかに進歩します。

よくある質問

APIオブザーバビリティとは何ですか？

APIオブザーバビリティとは、APIが発するテレメトリー、すなわちメトリクス、ログ、トレースから、APIの内部状態を理解する能力のことです。オブザーバブルなAPIは、新しい計装を追加することなく、予期しなかった問題を含め、なぜそのように動作するのかを調査することを可能にします。

APIオブザーバビリティとモニタリングの違いは何ですか？

モニタリングは、事前定義されたシグナルを監視し、しきい値を超えたときにアラートを発し、「壊れると予想していたものが壊れているか？」という問いに答えます。オブザーバビリティは、システムの特性であり、その振る舞いについて新しい任意の質問を可能にし、「なぜこれが起こっているのか？」という問いに答えます。モニタリングは何か問題があることを知らせ、オブザーバビリティはその原因を見つけるのに役立ちます。両方が必要です。

オブザーバビリティの3つの柱は何ですか？

3つの柱は、メトリクス、ログ、トレースです。メトリクスは、リクエストレートやレイテンシパーセンタイルなどの集計された数値です。ログは、個別のイベントのタイムスタンプ付き記録で、理想的にはJSONとして構造化されています。トレースは、サービス間を移動する1つのリクエストを追跡し、どこで時間が費やされたかを確認できるようにします。OpenTelemetryはこれらをテレメトリーシグナルとして形式化しています。

APIをオブザーバブルにするにはどうすればよいですか？

まず、すべてのリクエストでトレースIDを持つ構造化ログを生成することから始めます。OpenTelemetryでコードを計装し、メトリクス、ログ、トレースがコンテキストを共有するようにします。REDメトリクスを追跡し、SLIとSLOを目標として定義し、CIにコントラクトテストを追加し、本番環境に対してスケジュールされた合成チェックを実行します。各ステップでクエリ可能なシグナルが追加されます。

OpenTelemetryはオブザーバビリティに必須ですか？

いいえ。オブザーバビリティは、あらゆるテレメトリーツールで実現できる特性であり、多くのチームはOpenTelemetryが存在するはるか前から独自のエージェントを使用していました。とはいえ、OpenTelemetryはベンダーニュートラルなCNCF標準であるため、採用することで一度計装すれば、再計装することなくPrometheus、Datadog、Honeycombのようなバックエンドを切り替えることができます。これは強力なデフォルトであり、必須ではありません。