Cloud Monitoring メトリクス チートシート｜障害調査でよく使うPromQLまとめ

このチートシートの使い方

#

障害調査では「CPU が張り付いている VM はどれか」「5xx はいつから増えたか」といったクエリを何度も書きます。書くたびにメトリクス名とラベルを調べ直すと、そこで手が止まります。

このページは、調べたいことから貼り付けられるクエリへすぐたどり着くための早見表です。急いでいるときは、目的から探すへ直接進んでください。 そこからサービスから探すのクエリへ飛べます。

Metrics Explorer を開いたことがあり、クエリを素早く引きたい人向けです。Cloud Monitoring の入門とメトリクス収集の有効化は扱いません。アラートポリシー・SLO・ダッシュボードの設計も範囲外です。

集計やラベルの仕組みは解説編に、メトリクスが取れるかどうかの調べ方は確認編にあります。ここでは繰り返しません。

クエリを入力する場所

#

PromQL も Monitoring filter も Metrics Explorer に入力します。ただし入口が違います（Metrics Explorer の資料）。

見出しに「（Monitoring filter）」と付いたクエリ以外は、すべて PromQL です。 入力欄を切り替えると、入力中のクエリは破棄されます。

プレースホルダー

#

次の表にある語はプレースホルダーで、自分の環境の値に置き換えます。

各クエリの末尾にある「確認:」は、実データで確かめた範囲を示します。区分の意味と確認環境は、ページの最後にまとめています。

目的から探す

#

クエリ本体はサービスから探すに置いています。ここは行き先の一覧です。

Monitoring と Logging の使い分け

#

まず Monitoring で「いつ・どこで」を絞り、その時間帯とリソースで Logging を検索します。たとえばロードバランサの 5xx が増えていたら、個々のリクエストは Logging チートシートのグローバル外部 ALB の 5xxで見ます。

まず覚える PromQL

#

メトリクスをそのまま表示する

#

{"compute.googleapis.com/instance/cpu/utilization"}

メトリクス名に . や / が入るので、名前を引用符で囲んで波括弧の中に置きます。この書き方を UTF-8 記法と呼びます（PromQL の資料）。

古いダッシュボードには、compute_googleapis_com:instance_cpu_utilization のような legacy 名が残っていることがあります。最初の / を : に、残りの . と / を _ に置き換えた名前です（legacy 名への変換規則）。

このページでは UTF-8 記法で統一します。

PromQL では、resource ラベルも metric ラベルも、同じようにラベルとして扱えます。VM の場合、instance_id・zone（resource ラベル）と instance_name（metric ラベル）が並んで返りました。

確認: 実データ（ある1時刻では、VM 3台ぶんの3時系列。legacy 名でも同じ3時系列。4時間の範囲にすると、途中で作られた VM 2台が加わって5時系列）

monitored resource type を指定する

#

{"run.googleapis.com/request_count", monitored_resource="cloud_run_revision"}

メトリクスによっては、複数の monitored resource type に紐づきます。その場合は monitored_resource ラベルで種類を指定します（Specifying a monitored resource type）。

Cloud Run の request_count は cloud_run_revision と cloud_run_instance の2種類に紐づくので、指定しないとエラーになります。

must specify a label matcher on the 'monitored_resource' label because multiple monitored resource types [cloud_run_instance cloud_run_revision] are possible for metric type "run.googleapis.com/request_count"

紐づく種類は、メトリクス一覧の各エントリに載っています。このページで扱うメトリクスのうち、指定が必要なのは Cloud Run の3つだけです。

確認: 実データ（指定なしでエラー、cloud_run_revision を指定すると値が返った）

ラベルで絞る

#

{"compute.googleapis.com/instance/cpu/utilization", zone="ZONE", instance_name=~"INSTANCE_PREFIX.*"}

比較には =・!=・=~・!~ が使えます。正規表現は値全体との一致です。 前方一致なら末尾に .* を付けます（Prometheus 2.44: Instant vector selectors）。

resource 側と metric 側に同じ名前のラベルがあることもあります。そのときは metric 側に metric_ を付けて区別します（Resolving label conflicts）。

確認: 実データ（instance_name=~"tf-adv-elb08" は0件、.* を付けると2件）

平均・最大・合計でまとめる

#

avg by (zone) ({"compute.googleapis.com/instance/cpu/utilization"})

by (...) に、結果に残したいラベルを書きます。avg を max・min・sum・count に替えても、同じ形で使えます。

このページでは、max をCPU limit 使用率が高いコンテナ、sum をメモリ使用量が多い Pod、count をVM を数えるクエリで使っています。

平均では、1台だけ張り付いている状況が見えません。 解説編では、同じ zone の VM を平均すると 0.2343、最大を取ると 0.5071 でした。

確認: 実データ（zone ごとに1本ずつ、計2時系列）

上位だけを見る（topk）

#

topk(5, 式) は、値の大きい5本だけを残します。例はCPU 使用率が高い VM にあります。

グラフでは、線の本数が k を超えることがあります。 topk は時刻ごとに上位を選ぶので、途中で入れ替わった時系列もそれぞれ線として残ります。7時間の範囲で topk(3, ...) を実行したところ、11本が返りました。

rate と increase

#

increase(式[5m]) は5分間の増加量で、rate(式[5m]) はそれを1秒あたりに直した値です（Prometheus 2.44: Query functions）。

使うのは、metric kind が DELTA か CUMULATIVE のメトリクスです。 公式ドキュメントには、GAUGE に rate() を使うような型に合わない関数は Cloud Monitoring では動かない、と書かれています（Type-specific functions on differently typed metrics）。DELTA のメトリクスに rate() を使う例は、クォータの資料に載っています。

ただし、GAUGE である CPU 使用率に rate() をかけたところ、エラーにならずに値が返りました。 公式には非対応の使い方なので、返った値は使いません。kind は先にメトリクス一覧で確かめます。

[5m] のような区間がグラフのステップより短いと、区間はステップの長さまで広がります（Calculation of rate and increase）。

パーセンタイル（histogram_quantile）

#

DISTRIBUTION 型のメトリクスは、Prometheus のヒストグラムとして扱えます。名前の末尾に _bucket を付け、_count と _sum も使えます（PromQL の資料）。

形は histogram_quantile(0.95, sum by (le) (rate({"メトリクス名_bucket"}[5m]))) です。例は Cloud Run とロードバランサにあります。

• by に le を残します。 le はバケットの上限を表すラベルで、histogram_quantile() に必須です（Prometheus 2.44: histogram_quantile）。外してもエラーにはならず、警告 bucket label "le" is missing と0本の結果が返りました
• 値はバケットの境界から補間した推定値です（Prometheus 2.44: histogram_quantile）
• リクエストの無い時刻は、NaN ではなく点そのものが出ません（Calculation of histogram_quantile）

Monitoring filter の基本

#

metric.type="compute.googleapis.com/instance/cpu/utilization"
AND resource.type="gce_instance"
AND resource.labels.zone=starts_with("asia-northeast1")

Monitoring filter が決めるのは、どの時系列を出すかだけです。集計や alignment は書けないので、Metrics Explorer のメニューで選びます（Metrics Explorer の資料）。

時系列を取り出す filter には、metric.type を1つ指定します（Retrieving time series data）。このページの Monitoring filter はすべてこの形です。プロセス数や SLO を出す特殊な式は扱いません。

OR は AND より先に結び付きます。 混ぜるときは括弧を付けます（Comparisons）。

starts_with() などの関数は、文字列のラベルにしか使えません。 ロードバランサの response_code_class は INT64 なので、one_of("400", "500") と書くと次のエラーになります。

Function restrictions are only allowed for string type.

確認: 実データ

PromQL と使い分ける

#

ラベルの値を間違えたときの挙動も違います。 ロードバランサの response_code_class に "5xx" と書くと、Monitoring filter は型を確かめてエラーを返します。

The label 'response_code_class' is typed as an integer, but the supplied value '5xx' cannot be parsed as an integer.

同じ誤りでも、PromQL はエラーにならず0本を返すだけでした。Cloud Run に response_code_class="400" と書いた場合も0本です。PromQL で0本が返ったら、まずラベルの値の形を疑います。

サービスから探す

#

GKE / Kubernetes

#

GKE のシステム指標は kubernetes.io/ で始まります。コンテナの指標は k8s_container、Pod は k8s_pod、ノードは k8s_node に記録されます（Kubernetes metrics）。

どれも location と cluster_name で絞れ、コンテナと Pod の指標は namespace_name と pod_name でも絞れます（Monitored resource types）。

集計するときは by に location と cluster_name を残します。 残さないと、別の location にある同じ名前のクラスタや、別のクラスタにある同じ名前の Pod が1つにまとめられます。

CPU 使用率が高いノード

#

topk(5, {"kubernetes.io/node/cpu/allocatable_utilization", location="LOCATION", cluster_name="CLUSTER_NAME"})

Pod に割り当て可能な CPU（allocatable）のうち、使っている割合です。1 が 100% に当たります。

確認: 実データ

CPU limit 使用率が高いコンテナ

#

topk(10, max by (location, cluster_name, namespace_name, pod_name, container_name) ({"kubernetes.io/container/cpu/limit_utilization"}))

コンテナの CPU limit に対する使用率で、1 を超えることがあります。 コンテナが長時間 limit を超えて動ける場合があるためです（Kubernetes metrics）。

by に container_name まで残すので、どのコンテナかが分かります。

確認: 実データ

メモリ使用量が多い Pod

#

topk(10, sum by (location, cluster_name, namespace_name, pod_name) ({"kubernetes.io/container/memory/used_bytes"}))

used_bytes は memory_type ラベルで evictable と non-evictable の2本に分かれます。evictable はカーネルが容易に回収できるメモリです（Kubernetes metrics）。sum で Pod ごとの使用量にまとめます。

確認: 実データ（kube-system では evictable が約137MB、non-evictable が約369MB）

メモリ limit 使用率が高いコンテナ

#

max by (location, cluster_name, namespace_name, pod_name, container_name) ({"kubernetes.io/container/memory/limit_utilization", memory_type="non-evictable"}) > 0.8

limit に対するメモリの使用率で、1 を超えません。memory_type="non-evictable" で、カーネルが回収しにくいメモリだけを見ています。 回収できる分も含めるなら、この条件を外して sum by で足します。

> 0.8 は比較演算子で、0.8 を超えた時系列だけを残します。

確認: 実データ（閾値 0.8 では0件。0.4 に下げると11時系列が返った）

再起動している Pod

#

sum by (location, cluster_name, namespace_name, pod_name) (increase({"kubernetes.io/container/restart_count"}[1h])) > 0

restart_count は CUMULATIVE で、値は起動時からの累計です。そのまま表示しても、いつ再起動したかは読み取りにくいです。increase で1時間あたりの増分にし、増えた Pod だけを残します。

確認: 実データ（Pod 退避の検証でメモリを使い続けた Pod が、1時間に最大7回）

再起動回数を Namespace で絞る（Monitoring filter）

#

metric.type="kubernetes.io/container/restart_count"
AND resource.type="k8s_container"
AND resource.labels.namespace_name="NAMESPACE"

Monitoring filter は時系列を選ぶだけで、増分は計算しません。何回増えたかまで出すなら、PromQL の再起動している Podを使います。

確認: 実データ（5時系列）

ボリューム使用率が高い Pod

#

max by (location, cluster_name, namespace_name, pod_name, volume_name) ({"kubernetes.io/pod/volume/utilization"}) > 0.8

Pod の単位（k8s_pod）で記録されるメトリクスで、コンテナ名はありません。値は 1 を超えません（Kubernetes metrics）。

確認: 実データ（閾値 0.8 では0件。閾値を外した最大値は 0.55）

Compute Engine

#

VM の指標は compute.googleapis.com/instance/ で始まり、gce_instance に記録されます。VM の名前 instance_name は metric ラベルです。 resource ラベルにあるのは instance_id と zone です（解説編）。

集計するときは by に zone も残します。 残さないと、別のゾーンにある同じ名前の VM が1つにまとめられます。VM を同じ名前で作り直した前後を分けるなら、instance_id も残します。

CPU 使用率が高い VM

#

topk(5, {"compute.googleapis.com/instance/cpu/utilization"})

値はふつう 0.0〜1.0 で、グラフでは%で表示されます。API では生の値が返るので、0.14 が 14% です。マシンタイプによっては 1.0 を超えます（Compute Engine metrics）。

確認: 実データ

VM を名前で絞る（Monitoring filter）

#

metric.type="compute.googleapis.com/instance/cpu/utilization"
AND resource.type="gce_instance"
AND metric.labels.instance_name=starts_with("INSTANCE_PREFIX")

instance_name は metric ラベルなので、metric.labels. で指定します。resource.labels.instance_name と書くと、次のエラーになりました。

The supplied filter does not specify a valid combination of metric and monitored resource descriptors. The query will not return any time series.

確認: 実データ

ディスクの書き込み量

#

sum by (zone, instance_name) (rate({"compute.googleapis.com/instance/disk/write_bytes_count"}[5m]))

1秒あたりのバイト数です。読み込みは read_bytes_count に替えます。ディスクごとに分けるなら、by に device_name を足します。

確認: 実データ

ネットワークの送信量

#

sum by (zone, instance_name) (rate({"compute.googleapis.com/instance/network/sent_bytes_count"}[5m]))

受信は received_bytes_count に替えます。loadbalanced ラベルは、L3 ロードバランサの IP を経由した通信かどうかを表します（Compute Engine metrics）。

確認: 実データ

CPU 使用率を記録している VM を数える

#

count by (zone) ({"compute.googleapis.com/instance/cpu/utilization"})

CPU 使用率を記録している VM の数です。プロジェクトにある VM の数と一致するとは限りません。

確認: 実データ（asia-northeast1-a に2台、asia-northeast1-c に1台）

Cloud Run

#

このページで使う3つのメトリクスは、PromQL で monitored_resource の指定が要ります。 どれも複数の monitored resource type に紐づくためです（monitored resource type を指定する）。以下では、リビジョン単位の cloud_run_revision を指定します。

集計するときは by に location も残します。残さないと、別のリージョンにある同じ名前のサービスが1つにまとめられます。

response_code_class の値は "2xx" のような形です。ロードバランサの "500" とは形が違います。

公式のメトリクス一覧には、この値の一覧がありません。値の形は、SLO の資料にある Cloud Run の例（"2xx"・"4xx"）と、実データ（2xx・4xx）で確かめました。5xx の実データは無く、このページの "5xx" は同じ形を当てはめたものです。

リクエスト数

#

sum by (location, service_name) (rate({"run.googleapis.com/request_count", monitored_resource="cloud_run_revision"}[5m]))

1秒あたりのリクエスト数です。コンテナに届かなかったリクエストは数えません。 認証で拒否されたものや、最大インスタンス数に達して受けられなかったものです（Cloud Run metrics）。

確認: 実データ

5xx の件数

#

sum by (location, service_name) (increase({"run.googleapis.com/request_count", monitored_resource="cloud_run_revision", response_code_class="5xx"}[5m]))

各時刻の直前5分間に記録された 5xx の件数です。グラフの点の間隔は、この5分とは別に決まります。

確認: 置き換え（5xx の記録が無く0件。"4xx" に替えると、404 の2件が返った）

5xx 率

#

sum by (location, service_name) (rate({"run.googleapis.com/request_count", monitored_resource="cloud_run_revision", response_code_class="5xx"}[5m]))
/
sum by (location, service_name) (rate({"run.googleapis.com/request_count", monitored_resource="cloud_run_revision"}[5m]))

• 5xx が記録されていない時間帯は、0 ではなく線が欠けます。 分子の時系列が無いと、割り算の結果も作られないためです。分子に 0 の点があれば、率は 0 になります
• リクエストが0件の時間帯は、0÷0 で NaN になりました

確認: 置き換え（"4xx" に替えると 0.5）

p95 / p99 レイテンシ

#

histogram_quantile(0.99, sum by (location, service_name, le) (rate({"run.googleapis.com/request_latencies_bucket", monitored_resource="cloud_run_revision"}[5m])))

p95 にするなら、先頭の 0.99 を 0.95 に替えます。単位はミリ秒です。リクエストがコンテナに届いてから出るまでの時間で、コンテナの起動時間は含みません（Cloud Run metrics）。

確認: 実データ（同じサービス・同じ時刻で p99 が約281ms、p95 が約278ms。2時間の範囲での最大は p99 が約340ms）

インスタンス数

#

sum by (location, service_name, state) ({"run.googleapis.com/container/instance_count", monitored_resource="cloud_run_revision"})

state は active と idle の2つです（Cloud Run metrics）。active と idle を合計すると、その時点のインスタンス数になります。

確認: 実データ

5xx（Monitoring filter）

#

metric.type="run.googleapis.com/request_count"
AND resource.type="cloud_run_revision"
AND metric.labels.response_code_class="5xx"

Monitoring filter では、resource.type を省いてもエラーになりませんでした。PromQL とは扱いが違います。

確認: 置き換え（"4xx" に替えると1時系列）

Cloud Load Balancing

#

ここで扱うのは、グローバル外部 Application Load Balancer と classic Application Load Balancer です。

どちらも https_lb_rule に記録されます（ALB のログとモニタリング）。

リージョン外部 ALB は、メトリクス名と resource type が違います。 loadbalancing.googleapis.com/https/external/regional/request_count のように external/regional/ が入ります。resource type は http_external_regional_lb_rule です（Cloud Load Balancing metrics）。

以下のクエリをリージョン外部 ALB に使うときは、次のように書き換えます。

• PromQL と Monitoring filter の両方で、メトリクス名に external/regional/ を入れる
• Monitoring filter では、resource.type も http_external_regional_lb_rule にする
• 複数のリージョンにまたがって集計するなら、by に region も残す。region はこの resource type のラベルです（Monitored resource types）

response_code_class は INT64 で、値は 200・300・400・500・0 です（同上）。PromQL ではラベルの値を文字列で書くので、"500" と引用符で囲みます。

リクエスト数

#

sum by (forwarding_rule_name) (rate({"loadbalancing.googleapis.com/https/request_count"}[5m]))

URL マップやバックエンドサービスで分けるなら、by を url_map_name や backend_target_name に替えます。

確認: 実データ

5xx の件数

#

sum by (forwarding_rule_name, response_code) (increase({"loadbalancing.googleapis.com/https/request_count", response_code_class="500"}[5m]))

response_code を残すと、502 と 503 などを分けて見られます。

ロードバランサとバックエンドのどちらが返したかは、ログの statusDetails で確かめます（Cloud Logging チートシート）。

確認: 実データ（502 が5分間に最大24件）

5xx 率

#

sum by (forwarding_rule_name) (rate({"loadbalancing.googleapis.com/https/request_count", response_code_class="500"}[5m]))
/
sum by (forwarding_rule_name) (rate({"loadbalancing.googleapis.com/https/request_count"}[5m]))

5xx が記録されていない時間帯に線が欠けるのは、Cloud Run の 5xx 率と同じです。

確認: 実データ（すべてのリクエストが 502 だった時間帯で 1）

p95 レイテンシ

#

histogram_quantile(0.95, sum by (forwarding_rule_name, le) (rate({"loadbalancing.googleapis.com/https/backend_latencies_bucket"}[5m])))

backend_latencies は、プロキシがバックエンドへ送ってから、最後のバイトを受け取るまでの時間です。

クライアントへの応答まで含めるなら total_latencies に替えます。こちらは、プロキシがリクエストを受け取ってから、最後のバイトへの ACK がクライアントから届くまでの時間です（Cloud Load Balancing metrics）。

確認: 実データ（約301ms。total_latencies の p99 は約304ms）

5xx（Monitoring filter）

#

metric.type="loadbalancing.googleapis.com/https/request_count"
AND resource.type="https_lb_rule"
AND metric.labels.response_code_class=500

INT64 のラベルなので、数値で書きます。"500" と引用符を付けても同じ結果でした。metric.labels.response_code>=500 のように、大小比較もできます。

確認: 実データ（2時系列。response_code>=500 でも同じ2時系列）

よく使う組み合わせ

#

5xx 率が閾値を超えた時間だけ出す

#

(
  sum by (forwarding_rule_name) (rate({"loadbalancing.googleapis.com/https/request_count", response_code_class="500"}[5m]))
  /
  sum by (forwarding_rule_name) (rate({"loadbalancing.googleapis.com/https/request_count"}[5m]))
) > 0.05

5% を超えた時刻だけが線になるので、いつから悪化したかが一目で分かります。アラートの条件にするかどうかは別に判断します。アラートの設計は、このページの範囲外です。

確認: 実データ

前日の同じ時刻と比べる

#

avg({"compute.googleapis.com/instance/cpu/utilization"})
-
avg({"compute.googleapis.com/instance/cpu/utilization"} offset 1d)

offset 1d を付けると、1日前の値になります。差が正なら、前日より高いということです。1週間前と比べるなら offset 7d にします。

VM の構成が前日と違うと、その差も結果に入ります。 同じ VM だけを比べるなら、両辺を instance_name などのラベルで同じように絞ります。

確認: 実データ

値が取れないときは

#

PromQL は、条件に合う時系列が無くてもエラーにしません。 ラベルの値の形を間違えると、0本が返りました。le を落としたときも、警告1件付きで0本でした。

次の順に疑います。

1. ラベルの値の形。Cloud Run は "2xx" の形（"5xx" は実データでは未確認）、ロードバランサは "500"
2. 時間範囲。検証環境のように短時間しか動いていないリソースは、範囲が外れると0件になる
3. そのメトリクスが自分のプロジェクトに記録されているか

3 の調べ方は確認編にあり、定義があるか、データがあるか、応答が欠けていないかを順に見ます。

空が返ったときに疑う順は、解説編の「空が返ったときに疑う順」にもまとめてあります。

集計やラベルの意味を知りたいときは

#

このページは、どのクエリを書くかだけを扱いました。次のことは解説編にあります。

• metric kind・value type・unit の読み方
• alignment と reduction の違いと、集計を変えると値がどう変わるか
• resource ラベルと metric ラベルの違い
• v3 API・PromQL・MQL で同じ値を取る方法

確認環境とクエリの区分

#

Metrics Explorer は SaaS なので、読者が照合できる版番号がありません。代わりに、公式ドキュメントを確認した日付を書きます。

Google Cloud Console / Cloud Monitoring PromQL・Monitoring filter   2026-09-24 確認

Cloud Monitoring の PromQL は、公式に記載された差異を除き Prometheus 2.44 と同等です。それより後に追加された関数は使えないことがあります（PromQL compatibility）。

掲載したクエリは、API で実行して確かめました。PromQL は Prometheus 互換 API の query と query_range、Monitoring filter は timeSeries.list で実行しています。

対象は、このブログの検証環境で取得されて Cloud Monitoring に記録され、保持期間内に残っていたメトリクスです。

クエリごとに、確認した範囲を示しています。

まとめ

#

• このページでは、Google Cloud のメトリクス名を UTF-8 記法で書く。 名前を引用符で囲み、波括弧に入れる形（{"compute.googleapis.com/instance/cpu/utilization"}）
• このページの Cloud Run のメトリクスは、PromQL で monitored_resource の指定が要る。 複数の resource type に紐づくため、付けないとエラーになる。リビジョン単位で見るなら cloud_run_revision
• rate と increase は DELTA と CUMULATIVE に使う。 GAUGE への rate は公式には非対応。実測ではエラーにならず値が返ったが、その値は使わない
• パーセンタイルは _bucket と histogram_quantile。 by から le を落とすと、警告付きで0本になる
• response_code_class の値の形はサービスで違う。 Cloud Run は "2xx" の形、ロードバランサは 500（INT64）。Cloud Run の "5xx" は実データで確かめておらず、2xx・4xx の形から当てはめたもの
• ラベルの値を間違えても、PromQL はエラーにせず0本を返す。 Monitoring filter は型の合わない値をエラーにする
• 5xx 率の割り算は、5xx の時系列が無い時間帯に線が欠ける。 0 とは表示されない
• 集計では、リソースを区別するラベルを残す。 GKE は location と cluster_name、GCE は zone、Cloud Run は location
• 「どのくらい」は Monitoring、「何が」は Logging。 絞った時間帯とリソースでログを検索する

参考資料

#

• PromQL for Cloud Monitoring
• Select metrics when using Metrics Explorer
• Monitoring filters
• Google Cloud metrics
• Compute Engine metrics
• Cloud Load Balancing metrics
• Cloud Run metrics
• Kubernetes metrics
• Monitored resource types
• Cloud Monitoring API
• Chart and monitor quota metrics
• Request-response services（SLI の指標）
• External Application Load Balancer logging and monitoring
• Prometheus 2.44: Querying basics
• Prometheus 2.44: Query functions
• kubectl チートシート（構成の参考）
• よく使うCloud Monitoringメトリクスまとめ（解説編）
• Cloud Monitoringで取れるか調べる手順（確認編）
• Cloud Logging クエリ チートシート