Cloud Monitoringで取れるか調べる手順（定義はあるのに時系列は0件だった）

概要

#

監視項目を決めるとき、最初に詰まるのは名前ではありません。「そもそも取れるのか」が分からないことです。

メモリ使用率が見つからない。GKEのAPIサーバの指標が無い。Metrics Explorerを開いてもグラフが出ない。

原因が、収集していないのか、名前が違うのか、そもそも存在しないのか、画面からは区別がつきません。

この記事で扱うのは調べ方です。どの一覧を開き、何を読み、見つからなかったら次に何をするか。

メトリクスの一覧そのものは載せません。一覧はGoogle側で増減するので、写した記事はすぐ古くなります。

対になる記事があります。

Google Cloudのメトリクスを一度は触ったことがある人向けです。集計やPromQLの書き方、アラートポリシーの設計は扱いません。ログについてはクエリ集の記事があります。

検証環境

#

• Google Cloud SDK 562.0.0、Monitoring API v3
• 公式ドキュメントの確認日は2026年9月19日
• APIの実行は2026年9月19日、asia-northeast1 のリソースを対象

この記事の断定には2種類あります。公式ドキュメントを根拠にしたものと、実際にAPIを呼び出して確かめたものです。混ざらないように、実測した箇所には出力を載せています。

ただし実測の部分は追試できません。 検証環境は削除済みで、元のAPIレスポンスも保存していません。載せている数値は当時の記録を整形したもので、件数や値そのものを再確認する手立てがありません。数値ではなく、手順と読み方のほうを持ち帰ってください。 追試の条件は「見つかってもデータがあるとは限らない」の節に書いています。

一覧の分割やページ名は確認した時点のものです。公式の構成自体が変わることがあります。

公式の一覧はどこにあるか

#

入口はMetrics listです。ここから8つの一覧に分かれます。

分け方には基準があります。

Metric types in Cloud Monitoring are classified into general groups, based on the type of service that collects the data.

「データを収集するサービスの種類」で分かれています。言い換えると、どの一覧に載っているかを見れば、そのメトリクスの収集元と、取得に必要な仕組みの見当を付けられます。

Google Cloud metricsは量が多いため、さらに5ページに分かれています。A or B / C / D to H / I to O / P to Z です。

分かれる基準は製品名ではなく、メトリクスのサービスドメインです。

The reference pages list metric types by service domain

Cloud Run は製品名の頭文字が C ですが、サービスドメインは run.googleapis.com なので P to Z のページにあります。製品名で探すと別のページを開いてしまいます。

ここで「一覧の分かれ方＝収集方式」と覚えると行き過ぎです。分類はあくまで収集するサービスの種類で、課金や有効化の単位とは一致しません。判断の入口として使える、という程度に受け取ってください。

一覧・定義・実データの3層

#

一覧を読む前に、3つの層を分けておくと後が楽になります。公式の一覧そのものが、メトリクスの定義から生成されています。

Each metric type is formally described in a data structure called a metric descriptor.

The entries in these tables are created from the metric descriptors.

そして実際の測定値は、定義とは別の場所にあります。

A series of (timestamp, value) pairs. The value is the measurement, and the timestamp is the time at which the measurement was taken.

flowchart TD
    L["Metrics list
人が読む一覧"] -->|生成元| D["MetricDescriptor
メトリクスの定義"]
    D -->|定義に沿って記録される| T["TimeSeries
実際の測定値"]
    T --> P["Data Point
(timestamp, value)"]
    D -.->|metricDescriptors.list| API1["定義があるかを調べる"]
    T -.->|timeSeries.list| API2["データがあるかを調べる"]

この記事の結論を先に書くと、上の2本の点線は別物です。定義があることと、自分のプロジェクトにデータが流れていることは一致しません。

一覧のエントリで見る8項目

#

一覧の1行から読み取るのは次の8つです。

太字の3つは読み落としやすく、しかも読み落とすと判断を間違えます。

monitored resourceは「何に紐づくか」

#

Cloud Monitoringのモデルでは、時系列は3つの要素を持ちます。

Each time series encompasses the three components of the model: A description of the monitored resource from which the measurements originated. The set of measurements associated with a single monitored resource. A description of the metric type

メトリクス名が合っていても、期待したリソース種別で記録されるとは限りません。 名前だけで探して見つけたつもりになると、絞り込みの段で合わなくなります。

sample periodとlatencyは誤判定の元

#

公式の一覧には、収集間隔と遅延が説明文の末尾に入っています。

Sample Period: For metrics that are written periodically, this is the time interval between consecutive data points, excluding data loss due to errors. … The period, if available, appears at the end of the description text in a sentence of the form “Sampled every x seconds.”

Latency: Data points older than this value are guaranteed to be available to be read, excluding data loss due to errors. … appears … in a sentence of the form “After sampling, data is not visible for up to y seconds.”

リソースを作った直後にMetrics Explorerを開いて「取れない」と判断する事故は、ここを知らないと起きます。

ただし読み方に注意が要ります。公式の書き方は「この値より古いデータポイントは読めることが保証される」で、毎回その秒数だけ待たされるという意味ではありません。上限です。 起点もサンプリングの時点で、リソースを作った時点ではありません。

この保証には「エラーによるデータ欠損を除く」という条件が付いています。 上限を過ぎれば必ず読める、ではありません。この値が保証するのは、正常に取り込まれた測定点が読めるようになるまでの遅延の上限だけです。収集や取り込みに失敗した測定点がいつ現れるか、そもそも現れるかは、この値の範囲外です。一時的な失敗で遅れて入ることも、欠損したまま復元されないこともあります。

この2つは定義そのものにも入っています。実際に引くとこうなります。

PROJECT=$(gcloud config get-value project)
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/metricDescriptors?filter=metric.type%3D%22compute.googleapis.com/instance/cpu/utilization%22" \
  | jq '.metricDescriptors[] | {type, metricKind, valueType, unit, launchStage, metadata, monitoredResourceTypes}'

{
  "type": "compute.googleapis.com/instance/cpu/utilization",
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "unit": "10^2.%",
  "launchStage": "GA",
  "metadata": {
    "launchStage": "GA",
    "samplePeriod": "60s",
    "ingestDelay": "240s",
    "timeSeriesResourceHierarchyLevel": ["PROJECT"]
  },
  "monitoredResourceTypes": ["gce_instance"]
}

samplePeriod と ingestDelay は metadata の中にあります。

samplePeriod が60秒、ingestDelay が240秒です。

一覧の説明文にも同じ値が入ります。「Sampled every 60 seconds」「not visible for up to 240 seconds」の形で書かれています。

launch stageを読み飛ばさない

#

一覧には成熟度が付いています。

Each metric type has a launch stage that indicates its maturity. If specified, the launch stage appears as a colored superscript after the metric type: GA, BETA, ALPHA, EARLY_ACCESS, or DEPRECATED.

DEPRECATED を見落とすと、「取れるから採用しよう」と決めてしまいます。 実際に1つのプロジェクトから定義を引いて、launchStage を数えました。

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/metricDescriptors?pageSize=500" \
  | jq -r '.metricDescriptors[].launchStage' | sort | uniq -c | sort -rn

GA         267
BETA       193
ALPHA       34
DEPRECATED   6

これはコマンドの直接出力ではありません。uniq -c は件数を先に出すので、読みやすさのために列を入れ替えています。

6件あり、いずれも Vertex AI のクォータ関連でした。例として2件挙げると、

aiplatform.googleapis.com/quota/global_generate_content_input_tokens_per_minute_per_base_model_and_tier/usage
aiplatform.googleapis.com/quota/global_generate_content_requests_per_minute_per_project_per_base_model_and_tier/usage

この内訳は1プロジェクトの、pageSize=500 で取得した1ページぶんです。 検証環境は削除済みで元のレスポンスも残していないため、残り4件の名前は示せず、件数そのものも追試できません。

「先頭500件」という切り取り方にも意味はありません。metricDescriptors.list は nextPageToken があれば続きがあり、返る順序も保証されていないからです。比率として一般化できる数字ではありません。

確かめてほしいのは件数ではなく、採用候補の定義にある launchStage を採用前に見るということです。1ページに見当たらなくても、そのプロジェクトに DEPRECATED が無いとは判断できません。

探し方

#

サービスドメインが分かっているなら、その頭文字のページを開いて接頭辞で探すのが速いです。compute.googleapis.com なら C のページにあります。

製品名しか分からないときは、先にサービスドメインを調べてください。Cloud Run を C のページで探しても見つかりません。

名前がうろ覚えなら、プロジェクトから定義を引いて絞り込むほうが確実です。

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/metricDescriptors?pageSize=500" \
  | jq -r '.metricDescriptors[].type' | grep -i memory

これは1ページ目だけです。 レスポンスに nextPageToken があれば続きがあり、実際にこのプロジェクトでは返ってきました。1ページだけ見て0件でも、そのプロジェクトに定義が無いとは言えません。 続きを辿るか、filter で絞ってから引きます。

綴りで外しても0件になります。過去に kubelet_evictions_total を探して見つからず「存在しない」と書きかけたことがあります。実際の名前は kubelet_evictions でした。

見つからないとき

#

ここがこの記事の本題です。

公式の一覧に無いことは、「Cloud Monitoringで取れない」ことを意味しません。 正確には「標準提供されている公開メトリクスとしては確認できない」です。公式にこう書かれています。

Metric types in the Alpha or Early Access launch stages might not appear in the public lists of metrics.

To get information about those metric types, explicitly retrieve the set of metric descriptors from a Google Cloud project … by using the metricDescriptors.list method in the Monitoring API.

公開一覧に出ないものがある、と公式が明言しています。

見つからないときは、次の順に確認します。

1. 綴りと接頭辞、ページの取り違え。 Google Cloud metricsは5分割されている
2. Alpha / Early Access の可能性。 一覧に出ないことがある
3. 別の一覧の可能性。 Ops Agent、External metrics、Istio、Knativeは別ページ。GKEのPrometheus系（prometheus.googleapis.com/*）も別系統
4. ユーザー定義メトリクスの領分。 自分で作るものは一覧に無い。ただしログベースメトリクスは一括りにできない。システム定義のものは既定で用意され、公式一覧にも載る（Log-based metrics overview）。一覧に無いのはユーザー定義のほう
5. プロジェクトの実物を引く。 metricDescriptors.list は、そのプロジェクトで実際に使える定義を返す

5まで来て無ければ、そのプロジェクトからは定義を確認できません。それでも「製品として存在しない」とまでは言えません。 Alpha / Early Access など、利用権限が限定されたメトリクスがあります。

なお、通常の認証・権限不足やAPIの無効化は「0件」ではなくAPIエラーとして出ます。 先にHTTPステータスと error を見て切り分けてください。

見つかってもデータがあるとは限らない

#

一覧にあり、定義も引けた。それでもグラフが空、ということが起きます。定義があることと、自分のプロジェクトにデータが流れていることは別です。

先ほど定義を確認した compute.googleapis.com/instance/cpu/utilization を、直近2時間で引いてみます。

ST=$(date -u -d '-2 hours' +%Y-%m-%dT%H:%M:%SZ)
EN=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -s -G -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/timeSeries" \
  --data-urlencode 'filter=metric.type="compute.googleapis.com/instance/cpu/utilization"' \
  --data-urlencode "interval.startTime=$ST" --data-urlencode "interval.endTime=$EN"

{"unit": "10^2.%"}

timeSeries というキー自体が返っていません。 0件の配列ですらなく、単位だけが返ります。

このとき jq の書き方で挙動が分かれます。

$ echo '{"unit": "10^2.%"}' | jq '.timeSeries[]'
jq: error (at <stdin>:1): Cannot iterate over null (null)
$ echo $?
5

$ echo '{"unit": "10^2.%"}' | jq '.timeSeries[]?'
$ echo $?
0

素の .timeSeries[] は落ちます。 危ないのはむしろ ? を付けた形で、こちらは何も出さずに正常終了します。安全のつもりで付けると、空とエラーの区別が消えます。

空の結果とAPIの失敗も別物です。 認証切れや権限不足では error を含むレスポンスが返り、これも timeSeries キーを持ちません。キーの有無だけで「データが無い」と判断せず、HTTPステータスと error フィールドを先に見ます。

上のコマンドは説明のために -s を付けていますが、この形では通信エラーもHTTPステータスも見えません。 判断に使うなら -sS にして、ステータスも出します。

curl -sS -G -w '\nHTTP_STATUS=%{http_code}\n' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/timeSeries" \
  --data-urlencode 'filter=metric.type="compute.googleapis.com/instance/cpu/utilization"' \
  --data-urlencode "interval.startTime=$ST" --data-urlencode "interval.endTime=$EN"

さらに、HTTPが成功していても結果が欠けていることがあります。レスポンスの定義にこう書かれています。

executionErrors[]: Query execution errors that may have caused the time series data returned to be incomplete.

unreachable[]: Cloud regions that were unreachable which may have caused incomplete data to be returned.

nextPageToken: If there are more results than have been returned, then this field is set to a non-empty value.

この3つがあるうちは、返ってきた件数は「全部」ではありません。

「データが無い」と判断する前に見るものは4つです。curlの終了コード、HTTPステータス、error、そして executionErrors と unreachable。nextPageToken があれば、全ページを取り終えてから数えます。

同じメトリクスを、検索期間だけ7日に広げます。ST の作り方だけを変えました。

ST=$(date -u -d '-7 days' +%Y-%m-%dT%H:%M:%SZ)
EN=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -s -G -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://monitoring.googleapis.com/v3/projects/$PROJECT/timeSeries" \
  --data-urlencode 'filter=metric.type="compute.googleapis.com/instance/cpu/utilization"' \
  --data-urlencode "interval.startTime=$ST" --data-urlencode "interval.endTime=$EN"

timeSeries: 8 件
  resource : gce_instance
  metric   : {"instance_name": "tf-adv-elb10-a2"}
  points   : 14
  最新値   : 0.00559972292537149

これも直接出力ではありません。APIが返すのはJSONで、上は当時の記録を読みやすく整形したものです。8 件 は返ってきた時系列の数、その下の 14 点と最新値は、そのうち掲載したVM 1本ぶんの記録です。

定義が引けるメトリクスでも、期間の取り方しだいで0件になります。

ただしこの2回の実行では、窓だけが原因だったとまでは確かめていません。 記録が足りない点が3つあります。

• EN を実行時刻から作っているため、2回の終了時刻が揃っていない
• 取れた14点の時刻を残しておらず、7日側の点がすべて2時間の範囲外だったか分からない
• nextPageToken を辿ったかどうかの記録が無い

このプロジェクトは検証用で、VMは同じ日に作って削除しています。「VMを削除したから直近が空になった」という説明も、取り込み遅延という説明も、今回のデータでは否定できません。

切り分けるなら、プロジェクト・Metrics Scope・フィルタ・集計条件・EN を固定し、ST だけを変えて2回引きます。EN は取り込み遅延より十分に手前へ置き、全ページの応答・HTTPステータス・各点の時刻を保存しておくこと。

そのうえで7日側の点の時刻を見ます。すべて2時間の範囲外なら期間差で説明でき、範囲内にもあれば遅延などを疑い直すことになります。

値が 0.0056 なのは単位が 10^2.% だからで、0.56%です。コンソールは変換して表示しますが、APIは生の値を返します。

つまり確認は2段階です。

2段目が空だったときの疑う順は、よく使うCloud Monitoringメトリクスまとめにまとめてあります。時刻、名前、集計、リソース種別、収集の有無の順です。

取得できることと無料であることは別

#

取れると分かっても、そのまま有効にしてよいとは限りません。「GKEのメトリクスだから全部無料」ではありません。

根拠は次のとおりです。

Cloud Monitoring does not charge for the ingestion of GKE system metrics

GKE control plane metrics use Google Cloud Managed Service for Prometheus to load metrics into Cloud Monitoring. Cloud Monitoring charges for the ingestion of these metrics are based on the number of samples ingested.

kube stateも同じ仕組みで、同じ書き方で課金されます。Ops Agentについてはこうです。

If you install the Ops Agent, then you might be charged for the metrics, logs, or traces that the agent sends to your Google Cloud project.

この表は網羅ではなく、確かめた3種類だけを載せています。Google Cloudのサービス自身が出す指標など、課金されないものは他にもあります。正確なところは料金ページで確認してください。

押さえておくのは1点です。kubernetes.io と prometheus.googleapis.com は、どちらもGKEの指標でありながら扱いが違います。

読み取りAPIは取り込みとは別に課金される

#

ここまでの表はすべて「取り込み」の話です。読み取りには別の料金がかかります。 この記事で使っている curl による timeSeries.list は、その課金対象です。

Read API calls: $0.50/million time series returned

Read API calls: First 1 million time series returned per billing account

料金ページの Cloud Monitoring の表にこうあり、適用開始は2025年10月2日です。課金の単位は呼び出し回数ではなく、返ってきた時系列の数です。注記にはこう書かれています。

There is no charge for read API calls issued through the Google Cloud console, excluding those issued through the Cloud Shell. Read API calls that aren’t issued through the Google Cloud console and that can return time-series data are charged by the number of time series that are returned or for one time series, which ever is larger.

読み違えやすい条件が3つあります。

無料枠は請求先アカウントごとに月100万時系列で、同じアカウントの他の利用と共有します。 この記事の手順を数回試すだけでも、残量によっては課金されます。定期実行に組み込むときは、既存の利用量に各呼び出しの計上数を足して見積もってください。

補足：複数プロジェクトを見ているとき

#

Metrics Scopeを使っている環境では、どのプロジェクトを指定しているかで結果が変わります。

If the named project is not a scoping project of a metrics scope, then the methods retrieve data only from the named project.

If the named project is also a scoping project of a metrics scope, then the methods retrieve data from both the named project and any projects it monitors.

影響を受けるのは次の4つです。

The methods in this group are the following: timeSeries.list, timeSeries.query, metricDescriptors.list, monitoredResourceDescriptors.list

「このプロジェクトにメトリクスがある」と判断するとき、実は監視対象の別プロジェクトを見ていることがあります。 中央集約の構成では気をつけてください。

判断フロー

#

ここまでを1枚にします。

flowchart TD
    S["取りたい監視項目がある"] --> F["Metrics list で探す"]
    F -->|見つかった| R["エントリを読む
kind / unit / labels
monitored resource
launch stage
sample period / latency"]
    R --> C{"launch stage は
DEPRECATED か"}
    C -->|はい| ALT["後継を探す"]
    C -->|いいえ| E["収集に何が要るか確認
エージェント / 有効化"]
    E --> TS["timeSeries.list で
実データを確認"]
    TS --> Q{"応答は完全か
HTTP 成功 / error なし
executionErrors・unreachable なし
nextPageToken を辿り終えた"}
    Q -->|いいえ| RETRY["結果は不完全
件数で判断しない"]
    Q -->|はい| D{"時系列があるか"}
    D -->|ある| OK["使える"]
    D -->|無い| WIN["期間・遅延・リソース種別
収集の有無を疑う"]
    F -->|見つからない| N1["綴りとサービスドメイン
5分割のページ"]
    N1 --> N2["Alpha / Early Access"]
    N2 --> N3["別の一覧
Agent / 外部 / Istio / Knative"]
    N3 --> N4["ユーザー定義
ユーザー定義のログベース"]
    N4 --> N5["metricDescriptors.list で
プロジェクトの実物を引く
nextPageToken も辿る"]
    N5 -->|定義があった| R
    N5 -->|それでも無い| NG["そのプロジェクトからは
確認できない"]

まとめ

#

• 公式の一覧は収集するサービスの種類で8つに分かれる。 どの一覧に載っているかは、収集元と取得に要るものを見当づける手がかりになる。ただし課金や有効化の単位とは一致しない
• Google Cloud metricsは5ページに分かれる。基準は製品名ではなくサービスドメインで、Cloud Run は run.googleapis.com なので P to Z
• 一覧は定義（metric descriptor）から生成されている。 一覧・定義・実データは別の層
• エントリでは8項目を読む。monitored resource・launch stage・sample period / latency は読み落としやすい
• ingestDelay は待ち時間の上限で、起点はサンプリング時。 作った直後に見えないことを「取れない」と読まない。ただし保証は「エラーによるデータ欠損を除く」条件付きで、取り込みに失敗した測定点がいつ現れるかは保証の範囲外
• DEPRECATED を見落とすと、廃止予定のものを採用してしまう。 1プロジェクトを pageSize=500 で1ページ引いて6件あった（元の応答は残しておらず追試はできない）
• 一覧に無いことは「取れない」ではない。 Alpha / Early Access は公開一覧に出ないことがあると公式が明言している
• 見つからないときは、綴り → Alpha/EA → 別の一覧 → ユーザー定義・ログベース → metricDescriptors.list の順に確認する
• 定義があってもデータがあるとは限らない。 同じメトリクスで、2時間窓は0件、7日窓は8件だった。ただし終了時刻を固定していないため、窓だけが原因だとまでは切り分けていない
• データが無いとき、レスポンスに timeSeries キー自体が無い。 jq '.timeSeries[]' は Cannot iterate over null で落ち、? を付けた形は静かに何も出さない。APIの失敗時も同じくキーが無いので、先にステータスと error を見る
• HTTPが成功していても結果が欠けていることがある。 executionErrors・unreachable・nextPageToken を確認しないうちは、返った件数を「全部」として扱わない
• 取れることと無料で取れることは別。 同じGKEでも kubernetes.io は取り込みが課金されず、prometheus.googleapis.com はサンプル数で課金される
• 読み取りAPIは取り込みとは別料金。 2025年10月2日から、時系列を返せる読み取りAPIは「返却数と1の大きい方」で課金される。0件でも1ぶん計上される。 無料枠は請求先アカウントごとに月100万時系列で他の利用と共有。Metrics Explorer からの呼び出しは免除だが、Cloud Shell からは免除されない
• Metrics Scopeのscoping projectを指定すると、監視対象の別プロジェクトも検索範囲に入る

参考資料

#

• Metrics list
• Google Cloud metrics
• Kubernetes metrics
• Ops Agent metrics
• Components of the metric model
• Metrics, time series, and resources
• Introduction to the Cloud Monitoring API
• metricDescriptors.list
• timeSeries.list
• Configure metrics collection (GKE)
• Collect and view control plane metrics (GKE)
• Collect and view kube state metrics (GKE)
• Ops Agent
• Google Cloud Observability pricing