API 使用状況のモニタリング

このページでは、API 指標を使用して、Google APIs と Google Cloud APIs の使用状況を追跡、理解する方法について説明します。

Google API は、次のことに役立つ詳細な使用状況の指標を生成します。

Google API の使用状況を追跡、把握する。
アプリケーションと Google API のパフォーマンスをモニタリングする。
アプリケーションと Google API の間の問題を検出する。

問題をトラブルシューティングしたり、Google の技術サポートを受けたりすることで、解決にかかる時間を劇的に短縮できます。

Google API が生成する指標は、Google のサイト信頼性エンジニアがサービスの正常性を評価する際に使用する標準シグナルです。これらの指標の対象は、リクエスト数、エラー率、合計レイテンシ、バックエンドレイテンシ、リクエストサイズ、レスポンスサイズです。API 指標の定義については、Cloud Monitoring のドキュメントをご覧ください。

API 指標は、API ダッシュボードと Cloud Monitoring の 2 か所で表示できます。表示される指標はプロジェクトに固有のものであり、サービスのステータス全体を反映したものではありません。

API ダッシュボードを使用する

API 指標を表示する最も簡単な方法としては、Google Cloud コンソールの API ダッシュボードを使用します。このダッシュボードでは、API 使用に関するすべての指標状況の概要を表示することも、特定の API の使用状況を詳細に調べることもできます。

API 使用状況の概要については:

Cloud Console の [API とサービス] セクションに移動します。デフォルトで、メインの API ダッシュボードが表示されます。このページで、プロジェクトに現在有効にされているすべての API と、次の指標の概要を示すグラフを確認できます。
- トラフィック: API が有効にされているプロジェクトによって行われる、またはプロジェクトに関する 1 秒あたりのリクエスト数
- エラー: 有効にされている API に対して行ったすべてのリクエストのうち、エラーが発生したリクエストの割合
- 中央値のレイテンシ: 有効にされている API に対するリクエストでの中央値のレイテンシ（利用可能な場合）。

特定の API の使用状況の詳細を表示するには、次の手順に従います。

メインの API ダッシュボードに表示される API のリストで、詳細を表示する API を選択します。その API の概要ページに、レスポンスコード別の内訳を示す、詳細なトラフィックグラフが表示されます。
使用状況に関する情報をさらに詳しく調べるには、[指標を表示] を選択します。デフォルトでは、事前に作成されている次のグラフが表示されます。ただし、表示できるグラフは他にもあります。
- レスポンスコード別のトラフィック
- API メソッド別のエラー数
- 50 番目、95 番目、99 番目のパーセンタイルにおける全体的なレイテンシ
- API メソッド別のレイテンシ（中央値）
グラフをさらに追加するには、[グラフを選択] プルダウンメニューから、事前に作成されている追加のグラフを選択します。

Cloud Monitoring の使用

Cloud Monitoring を使用している場合は、API の使用状況をより詳細に把握するため、Metrics Explorer を使用して、利用可能な指標データを詳しく分析できます。Cloud Monitoring はさまざまな指標をサポートしています。このような指標とフィルタや集計を組み合わせることで、アプリケーションのパフォーマンスを詳しく分析できます。たとえば、リクエスト数の指標を HTTP レスポンスコードクラスのフィルタと組み合わせて、一定期間にわたるエラー率を示すダッシュボードを作成したり、Cloud Pub/Sub API に対するリクエストについて、95 番目のパーセンタイルにおけるレイテンシを調べたりできます。

利用可能な指標

次の表に、使用可能な serviceruntime 指標の一覧を示します。API 使用状況の指標は、モニタリング対象リソースとして consumed_api を含む指標です。

次の表の指標タイプの文字列には、serviceruntime.googleapis.com/ という接頭辞を付ける必要があります。この接頭辞は表内で省略されています。ラベルをクエリする場合は、metric.labels. 接頭辞を使用します（例: metric.labels.LABEL="VALUE"）。

指標タイプ^{リリースステージ} （リソース階層レベル）表示名
種類、タイプ、単位モニタリング対象リソース	説明ラベル
`api/request_count` ^GA *（プロジェクト）* リクエスト数
`DELTA`, `INT64`, `1` api consumed_api produced_api	完了したリクエストの数。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。 `protocol`: リクエストのプロトコル（例: 「http」、「grpc」）。 `response_code`: HTTP リクエストの場合は HTTP レスポンスコード、gRPC リクエストの場合は対応する HTTP コード。https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto でコードマッピングをご覧ください。 `response_code_class`: HTTP リクエストの場合はレスポンスコードクラス、gRPC リクエストの場合は対応する HTTP クラス（例: 「2xx」、「4xx」）。 `grpc_status_code`: gRPC リクエストの場合は gRPC の数値レスポンスコード、HTTP リクエストの場合は対応する gRPC コード。https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto でコードマッピングをご覧ください。
`api/request_latencies` ^GA *（プロジェクト）* リクエストのレイテンシ
`DELTA`, `DISTRIBUTION`, `s` api consumed_api produced_api	: 非ストリーミングリクエストのレイテンシ（秒）の分布。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。
`api/request_latencies_backend` ^GA *（プロジェクト）* リクエストのバックエンドレイテンシ
`DELTA`, `DISTRIBUTION`, `s` api produced_api	非ストリーミングリクエストに対するバックエンドレイテンシ（秒）の分布。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。
`api/request_latencies_overhead` ^GA *（プロジェクト）* リクエストのオーバーヘッドレイテンシ
`DELTA`, `DISTRIBUTION`, `s` api produced_api	バックエンドを除く、非ストリーミングリクエストのレイテンシ（秒）の分布。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。
`api/request_sizes` ^GA *（プロジェクト）* リクエストサイズ
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	リクエスト完了時に記録されたリクエストサイズの分布（バイト）。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。
`api/response_sizes` ^GA *（プロジェクト）* レスポンスサイズ
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	リクエスト完了時に記録されたレスポンスサイズの分布（バイト）。60 秒ごとにサンプリングされます。サンプリング後、データは最長 1,800 秒間表示されません。
`quota/allocation/usage` ^GA *（プロジェクト、フォルダ、組織）* 数量に基づく割り当ての使用量
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	消費された数量に基づく割り当ての合計。1 分あたり 1 を超える値が報告された場合、その値は破棄されます。割り当て使用量で変更を受信しなかった場合は、最後の値が少なくとも 24 時間ごとに繰り返されます。60 秒ごとにサンプリングされます。 `quota_metric`: 割り当て指標または割り当てグループの名前。
`quota/concurrent/exceeded` ^ALPHA *（プロジェクト、フォルダ、組織）* 同時実行割り当ての超過
`DELTA`, `INT64`, `1` consumer_quota	同時実行割り当てを超える試行回数。86400 秒ごとにサンプリングされます。サンプリング後、データは最長 180 秒間表示されません。 `limit_name`: 割り当て上限の名前（「1 日あたりのリクエスト数」や「使用中の IP アドレス数」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。 `time_window`: 同時実行オペレーションの上限のウィンドウサイズ。
`quota/concurrent/limit` ^ALPHA *（プロジェクト、フォルダ、組織）* 同時実行割り当ての上限
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	割り当ての同時実行の上限。86400 秒ごとにサンプリングされます。サンプリング後、データは最長 180 秒間表示されません。 `limit_name`: 割り当て上限の名前（「1 日あたりのリクエスト数」や「使用中の IP アドレス数」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。 `time_window`: 同時実行オペレーションの上限のウィンドウサイズ。
`quota/concurrent/usage` ^ALPHA *（プロジェクト、フォルダ、組織）* 同時実行割り当ての使用量
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	割り当ての同時使用。60 秒ごとにサンプリングされます。サンプリング後、データは最長 180 秒間表示されません。 `limit_name`: 割り当て上限の名前（「1 日あたりのリクエスト数」や「使用中の IP アドレス数」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。 `time_window`: 同時実行オペレーションの上限のウィンドウサイズ。
`quota/exceeded` ^GA *（プロジェクト、フォルダ、組織）* 割り当て超過エラー
`GAUGE`, `BOOL`, `1` consumer_quota	割り当て上限を超えた時点でエラーが発生しました。60 秒ごとにサンプリングされます。 `limit_name`: 割り当て上限の名前（「1 日あたりのリクエスト数」や「使用中の IP アドレス数」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。
`quota/limit` ^GA *（プロジェクト、フォルダ、組織）* 割り当て上限
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	割り当ての上限。86,400 秒ごとにサンプリングされます。 `limit_name`: 割り当て上限の名前（「1 日あたりのリクエスト数」や「使用中の IP アドレス数」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。
`quota/rate/net_usage` ^GA *（プロジェクト、フォルダ、組織）* レート割り当ての使用量
`DELTA`, `INT64`, `1` consumer_quota producer_quota	消費レートの総割り当て60 秒ごとにサンプリングされます。サンプリング後、データは最長 240 秒間表示されません。 `method`: API メソッドの名前（「disks.list」など）。 `quota_metric`: 割り当て指標または割り当てグループの名前。
`reserved/metric1` ^EARLY_ACCESS *（プロジェクト）* 非推奨
`DELTA`, `INT64`, `1` deprecated_resource	サポートを終了しました。60 秒ごとにサンプリングされます。サンプリング後、データは最長 180 秒間表示されません。 `quota_name`: 非推奨。 `credential_id`: 非推奨。 `quota_location`: 非推奨。

表の生成日時: 2025-02-06 13:34:14 UTC

Metrics Explorer で API 指標を表示するには、リソースタイプとして [Consumed API] を選択してから、serviceruntime 指標のいずれかを選択します。次にフィルタと集計のオプションを使用して、データを絞り込みます。目的の API 使用量の情報が見つかったら、Cloud Monitoring を使用してカスタムダッシュボードとアラートを作成し、継続的なモニタリングによって堅牢なアプリケーションを維持できます。方法については、次のページをご覧ください。

詳しくは、Metrics Explorer をご確認ください。

API 指標を使用したトラブルシューティング

問題が発生したときに Google に連絡する必要がある場合は、API 指標がとりわけ役立ちます。API 指標を調べることで、サポートへの連絡が不要になることさえあります。次に例を示します。

特定の認証情報の ID では、サービス呼び出しがすべて失敗する一方、他の ID では失敗しない場合は、おそらくそのアカウントに問題があります。アカウントの問題は、チケットをオープンしなくても自力で簡単に解決できます。
アプリケーションの問題をトラブルシューティングしていて、アプリケーションのパフォーマンス低下と重要な GCP サービスの 50 番目のパーセンタイルにおけるレイテンシとの間に相関関係があることに気付いたとします。その場合は、必ずサポートに連絡して、できるだけ迅速にサポートが問題に取り組めるよう、そのデータを指摘してください。
GCP サービスレポートでのレイテンシには問題がなく、以前と何も変わっていない一方、アプリケーション内の指標では、サービス呼び出しのレイテンシが異常に長いことが示されているとします。これは、ネットワークに問題があることを意味します。ネットワークプロバイダ（場合によっては Google）に連絡して、デバッグプロセスの開始をご依頼ください。

ベストプラクティス

API 指標は極めて有用なツールですが、API 指標が有用な情報であることを確実にするためには、いくつか考慮しなければならない点があります。こうした考慮事項は、指標の値に基づいてアラートを設定する際はなおさら重要になります。API 指標のデータを最大限に活用するには、次のベストプラクティスを参考にしてください。

レイテンシが原因で問題が発生していますか？

レイテンシの影響を受けやすいサービスもあれば、スケールや信頼性のほうが重要なサービスもあります。たとえば、一部の API、Cloud Storage、BigQuery では、ユーザーは気付かなくても、数秒もの高いレイテンシが生じることがあります。API 指標のデータを調べれば、ユーザーが特定のサービスに求めていることを把握できます。

通常との違いを見つけること

特定の指標の値に基づいてアラートを出す前に、実際に何が通常と異なる動作なのかを考えてください。API 指標を調べると、ほとんどのサービスではレイテンシが通常の分布曲線の中に収まっていることがわかります。つまり、レイテンシの値のほとんどは中央に集まっていて、その上下に外れ値が散らばっているという分布です。このように、指標を利用して通常の分布を把握すれば、アプリケーションの動作が分布曲線の中に収まるよう調整できます。また、指標を利用すると、分布の変化とアプリケーションが正常に動作していない期間を関連付けられるので、問題の根本原因を突き止めるうえでも役立ちます。99 番目のパーセンタイルは中央値と大きく異なっているはずですが、これらのパーセンタイルが時間とともに大幅に変わることはないはずです。

また、特定の種類のリクエストに、他のリクエストよりも時間がかかっていることがわかる場合もあります。たとえば、Google フォトにアップロードする写真のサイズの中央値が 4 MB であるのに対し、自分が通常アップロードする RAW ファイルサイズが 20 MB だとすると、20 点の写真をアップロードするのにかかる平均所要時間はほとんどのユーザーより大幅に長くなるはずですが、それでもそれが、自分にとっての通常の動作です。

以上のことから、RPC や 5xx HTTP 呼び出しに 1 秒かかっていることを初めて検出したときにアラートを出しても、それほど意味はありません。アラートを出す代わりに、アプリケーションで発生している問題の潜在的原因として Google サービスを調査し、一定期間にわたる戻りコードとレイテンシの変化量を比較して、アプリケーションで観測された問題と関連する、通常の動作との大きな違いを見つけてください。

トラフィックレート

大量のトラフィックが API に流れる場合、API 指標はとりわけ役立ちます。一方、サービスをたまに呼び出すだけの場合は、API 指標は統計として有効ではなく、有意義なトリアージ情報にはなりません。

たとえば、99.5 番目のパーセンタイルにおけるサービスのレイテンシをトラッキングするとします。このとき、1 時間に 100 回の呼び出ししか行わなければ、2 時間にわたる測定で観測できる、99.5 番目のパーセンタイルを表すデータポイントは 1 つだけとなります。これでは、API やアプリケーションの通常の動作についてはほとんど把握できません。トラフィックレート、トラッキング対象のパーセンタイル、そして観測する時間枠で対象とするデータポイントが多数生成されるようにしなければ、モニタリングデータは役に立たないものとなってしまいます。

サポートされている API

すべての Google API、Google Cloud APIs のほか、Cloud Endpoints、API ゲートウェイ上に構築された API も、API 指標をサポートしています。API コンシューマの場合は、API ダッシュボードに消費した API 指標が表示されます。API プロデューサーの場合は、エンドポイントダッシュボードに Produced API の指標が表示されます。