DEV Community

Cover image for API可観測性：概要と実現方法
Akira
Akira

Posted on • Originally published at apidog.com

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

APIオブザーバビリティとは、APIが発するテレメトリー（メトリクス、ログ、トレース）を使って、APIが「なぜそのように動作しているのか」を理解できる状態にすることです。単にダッシュボードを見るだけではなく、すでに収集しているデータから、想定外の障害や遅延についても調査できるようにします。

Apidogを今すぐ試す

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

制御理論では、システムの外部出力から内部状態を推測できる場合、そのシステムは「可観測（observable）」であるとされます。

APIに当てはめると、次のような状態です。

  • 新しいログを追加して再デプロイしなくても調査できる
  • メトリクス、ログ、トレースが同じリクエストに紐付いている
  • 特定のユーザー、地域、APIバージョン、エンドポイント単位で原因を絞り込める
  • 予期していなかった障害モードにも対応できる

たとえば、ユーザーから「午前2時に特定リージョンのチェックアウトAPIが遅い」と報告されたとします。オブザーバブルなAPIであれば、既存のテレメトリーから次のように調査できます。

  1. p99レイテンシが急上昇した時間帯を確認する
  2. 対象のAPIバージョンとリージョンで絞り込む
  3. 遅いリクエストのトレースを見る
  4. 問題のサービスや外部依存を特定する
  5. 同じ trace_id を持つログを確認する

これは、単なる稼働確認とは目的が異なります。

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

モニタリングとオブザーバビリティは関連しますが、役割が異なります。

モニタリングは、事前に決めたシグナルを監視し、しきい値を超えたら通知します。たとえば、エラー率、CPU使用率、p99レイテンシなどです。

オブザーバビリティは、システムが十分なテレメトリーを出しているため、あとから任意の質問を投げられる状態です。

簡単に言うと、モニタリングは「問題が起きた」ことを知らせます。オブザーバビリティは「なぜ起きたか」を調べるための手段です。アラート設計については、APIモニタリングガイドも参考になります。

側面 モニタリング オブザーバビリティ
回答する質問 既知のシグナルが範囲外か？ なぜシステムはこのように動作しているのか？
定義タイミング 事前 調査時
得意な領域 既知の障害、SLO違反 新規の予期しない問題
出力 アラート、ステータスダッシュボード 高カーディナリティでクエリ可能なテレメトリー

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

APIオブザーバビリティは、主に以下の3種類のテレメトリーで構成します。

  • メトリクス
  • ログ
  • トレース

OpenTelemetryでは、これらをテレメトリーの「シグナル」として扱います。現在はトレース、メトリクス、ログ、バゲージをサポートしており、イベントとプロファイルも開発中です。

メトリクス

メトリクスは、時間経過に沿って集計される数値データです。APIでは、まず次を計測します。

  • リクエスト数
  • エラー率
  • レイテンシ
  • p95 / p99 レイテンシ
  • スループット

平均レイテンシだけを見るのは避けます。平均値は、実際のユーザーが体感する遅いリクエストを隠してしまうためです。

例：

http_requests_total
http_request_duration_seconds_bucket
http_requests_errors_total
Enter fullscreen mode Exit fullscreen mode

メトリクスは保存コストが低く、クエリが速いため、ダッシュボードやアラートに向いています。ただし、メトリクスだけでは「どのリクエストが遅かったのか」までは追いにくいです。

ログ

ログは、個別イベントのタイムスタンプ付き記録です。APIでは、自由形式のテキストログよりも、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"
}
Enter fullscreen mode Exit fullscreen mode

重要なのは trace_id です。このIDにより、ログとトレースを同じリクエスト単位で関連付けられます。

ログに最低限含めたいフィールドは次のとおりです。

timestamp
level
method
path
status
duration_ms
trace_id
request_id
user_region
api_version
Enter fullscreen mode Exit fullscreen mode

トレース

分散トレースは、1つのリクエストが複数サービスを通過する流れを可視化します。

たとえば、チェックアウトAPIが次のような経路を通るとします。

API Gateway
  -> Auth Service
  -> Cart Service
  -> Payment Service
  -> Notification Service
Enter fullscreen mode Exit fullscreen mode

トレースがあれば、どのサービスで時間がかかったのかをスパン単位で確認できます。

トレースがない場合、マイクロサービス環境では「どのサービスが遅いのか」を推測するしかありません。トレースはその推測を実測に変えます。

実際の調査では、次の流れが基本です。

  1. メトリクスでレイテンシやエラーのスパイクを検知する
  2. トレースで遅いサービスや外部依存を特定する
  3. 同じ trace_id のログを確認する
  4. 原因を修正する

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

すべてを最初から計測する必要はありません。APIでは、まずREDメソッドから始めるのが実用的です。

REDは次の3つです。

  • Rate（レート）: 1秒あたりのリクエスト数
  • Errors（エラー）: 失敗したリクエスト数または割合
  • Duration（期間）: リクエストレイテンシの分布 
Rate     = 1秒あたりのリクエスト数
Errors   = 5xx応答、および予期しない4xx応答の割合
Duration = p95 / p99 を含むレイテンシ分布
Enter fullscreen mode Exit fullscreen mode

REDはリクエスト駆動型サービス、API Gateway、サービスメッシュと相性がよい方法です。

一方、CPU、メモリ、ディスク、ネットワークなどのインフラリソースにはUSEメソッドを使います。

Utilization = 使用率
Saturation  = 飽和度
Errors      = エラー
Enter fullscreen mode Exit fullscreen mode

APIでは、まずREDを実装し、その下のホストやコンテナにはUSEを追加します。

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

メトリクスを収集するだけでは不十分です。運用で使うには、目標に変換する必要があります。

SLI

SLI（Service Level Indicator）は、サービス品質を表す定量的な指標です。

APIでは次のようなものが代表例です。

  • 成功率
  • エラー率
  • レイテンシ
  • スループット
  • 可用性

SLO

SLO（Service Level Objective）は、SLIに対する目標値です。

例：

28日間の全リクエストの99.9%が300ms未満で完了する
Enter fullscreen mode Exit fullscreen mode

SLOがあると、チームは次を判断できます。

  • 現在のAPIは十分に健全か
  • 信頼性改善を優先すべきか
  • 新機能開発を継続できるか
  • エラーバジェットを消費しすぎていないか

SLIとSLOがない場合、レイテンシグラフは単なる波形です。SLOを定義すると、運用判断に使える契約になります。

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

オブザーバビリティのツールは、次の2層に分けて考えると実装しやすくなります。

  1. テレメトリーを生成する層
  2. テレメトリーを保存・分析する層

生成層：OpenTelemetry

OpenTelemetryは、CNCFのベンダーニュートラルな標準です。OpenTracingとOpenCensusを統合して作られました。

OpenTelemetryを使うと、次を共通化できます。

  • API
  • 言語SDK
  • セマンティック規約
  • OTLPプロトコル
  • 自動計装
  • OpenTelemetry Collector

最大の利点は、バックエンドに依存しないことです。一度計装すれば、再計装せずに送信先を切り替えやすくなります。

保存・分析層

代表的な選択肢は次のとおりです。

  • Prometheus + Grafana
  • Datadog
  • Honeycomb
  • その他のログ・トレース基盤

PrometheusとGrafanaは、メトリクスとダッシュボードのオープンソース構成としてよく使われます。DatadogやHoneycombのような商用プラットフォームは、メトリクス、ログ、トレースを統合し、高カーディナリティなクエリを扱いやすくします。

Datadogを使う場合は、Datadog APIのウォークスルーで、API経由でデータを送受信する方法を確認できます。

テストと合成チェックをオブザーバビリティに組み込む

オブザーバビリティは本番環境だけの話ではありません。CIでのテスト結果や、本番環境に対する合成チェックも重要なシグナルです。

シフトレフト：コントラクトテストをCIで実行する

デプロイ前に、APIが仕様どおりに動作するかを検証します。これにより、破壊的変更をユーザーに届く前に検出できます。

CIで実行されるテストは、次の情報を持つオブザーバビリティデータになります。

  • コミット
  • ブランチ
  • 環境
  • 実行時刻
  • 成功 / 失敗
  • レイテンシ
  • レポート

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

npm install -g apidog-cli

# インストール確認
node -v && apidog -v
Enter fullscreen mode Exit fullscreen mode

環境に対してテストシナリオを実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Enter fullscreen mode Exit fullscreen mode

各オプションの意味は次のとおりです。

-t = テストシナリオID
-e = 環境ID
-r = レポート形式（cli, html, json, junit）
Enter fullscreen mode Exit fullscreen mode

CSVまたはJSONファイルからデータ駆動テストを行う場合は、-d または --iteration-data を使います。

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  -d ./data.csv
Enter fullscreen mode Exit fullscreen mode

レポート概要をApidog Cloudにアップロードする場合は、--upload-report を追加します。

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

CI/CDへの組み込み例は、CI/CDガイド向けApidog CLIと完全なCLIリファレンスを参照してください。

本番環境で合成モニタリングを実行する

合成モニタリングは、実ユーザーの代わりにスクリプト化されたリクエストを定期実行する方法です。

たとえば、次のようなチェックを外部から実行します。

GET /health
POST /login
GET /me
POST /checkout
Enter fullscreen mode Exit fullscreen mode

基本的なAPIヘルスチェックは最小構成です。より高度な合成モニタリングでは、ログインからチェックアウトまでのような複数ステップのフローを検証します。

合成チェックの結果は、それ自体がシグナルです。

{
  "check": "checkout-flow",
  "status": "failed",
  "duration_ms": 4000,
  "region": "ap-southeast-1",
  "timestamp": "2026-06-22T02:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

午前2時に4秒かかって失敗した合成チェックは、トレースやログと関連付けて調査すべきイベントです。

ツール選定では、合成テストツールやAPIモニタリングツールの比較も参考になります。

Apidogスケジュールタスクで定期シグナルを生成する

Apidogでは、スケジュールタスクを使ってテストシナリオを定期実行できます。設定済みのシナリオを指定した時間に実行し、結果をキャプチャすることで、継続的な回帰テストと合成シグナルを作れます。

この機能は「テスト」モジュール内の「スケジュールタスク」から利用できます。

設定時に選ぶ主な項目は次のとおりです。

  • テストシナリオ: 実行する1つまたは複数のシナリオ
  • 実行モード: 毎週日曜23時、6時間ごとなど
  • 通知: 毎回通知するか、失敗時のみ通知するか
  • 実行環境: どの環境に対して実行するか

注意点もあります。

  • スケジュールタスクは現在ベータ版です
  • 設定済みのセルフホスト型Runnerが必要です
  • 「Runs On」にはセルフホスト型Runnerが表示されます
  • Apidog Cloudは近日利用可能と記載されています
  • 実行回数はサブスクリプションプランに依存します

詳細な手順は、Apidogスケジュールタスクのウォークスルーを参照してください。

設計、テスト、定期実行を同じシナリオで回せると、APIのパス / フェイルとレイテンシを継続的な運用シグナルとして扱えます。

オブザーバブルなAPIを作る手順

ゼロから始める場合は、次の順序で進めると実装しやすいです。

1. 構造化ログを出す

すべてのリクエストで、一貫したJSONログを出します。

最低限、次を含めます。

timestamp
level
method
path
status
duration_ms
trace_id
request_id
Enter fullscreen mode Exit fullscreen mode

2. トレースIDを全サービスで伝播する

API Gatewayから下流サービスまで、同じ trace_id を渡します。

Gateway -> Auth -> Checkout -> Payment
Enter fullscreen mode Exit fullscreen mode

すべてのログとスパンに同じIDを入れることで、調査時に横断検索できます。

3. OpenTelemetryで計装する

OpenTelemetryを使い、メトリクス、ログ、トレースのコンテキストを揃えます。

目的は、ツールに依存しない形でテレメトリーを生成することです。

4. REDメトリクスをダッシュボード化する

まずは次を可視化します。

  • Rate
  • Errors
  • Duration p95
  • Duration p99

平均値だけでなく、p95 / p99 を必ず見ます。

5. SLIとSLOを定義する

例：

28日間の99.9%のリクエストが300ms未満
5xxエラー率が0.1%未満
Enter fullscreen mode Exit fullscreen mode

SLOを超えた場合に、機能開発より信頼性改善を優先する基準にします。

6. CIにコントラクトテストを追加する

API仕様と実装のずれを、デプロイ前に検出します。

テスト結果をレポートとして保存し、失敗率や実行時間も追跡します。

7. 本番環境で合成チェックを実行する

定期的に本番APIへリクエストを送り、可用性とレイテンシを監視します。

Apidogのスケジュールタスクのような仕組みを使うと、既存のテストシナリオをそのまま継続的なシグナルにできます。

最小構成から始めるなら

最初からすべてを導入する必要はありません。最小構成なら、次の3つから始めます。

1. trace_id付きの構造化ログ
2. REDメトリクス
3. 本番環境への合成チェック
Enter fullscreen mode Exit fullscreen mode

これだけでも、フラットなテキストログと手動確認だけの状態より大きく改善します。

よくある質問

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

APIが発するメトリクス、ログ、トレースから、APIの内部状態を理解できる能力です。オブザーバブルなAPIでは、新しい計装を追加しなくても、予期しなかった問題について「なぜ起きたのか」を調査できます。

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

モニタリングは、事前定義されたシグナルを監視し、しきい値を超えたら通知します。オブザーバビリティは、テレメトリーを使ってシステムの振る舞いについて任意の質問を投げられる状態です。モニタリングは問題の検知、オブザーバビリティは原因調査に役立ちます。

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

メトリクス、ログ、トレースです。メトリクスは集計された数値、ログは個別イベントの記録、トレースは1つのリクエストがサービス間を移動する流れを表します。

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

まず、すべてのリクエストで trace_id を含む構造化ログを出します。次にOpenTelemetryで計装し、REDメトリクスを追跡します。そのうえでSLIとSLOを定義し、CIにコントラクトテストを追加し、本番環境に対して合成チェックを実行します。

OpenTelemetryは必須ですか？

必須ではありません。オブザーバビリティは、任意のテレメトリーツールで実現できます。ただし、OpenTelemetryはベンダーニュートラルなCNCF標準であり、一度計装すればPrometheus、Datadog、Honeycombなどのバックエンドを切り替えやすくなります。

Top comments (0)