您可以使用 PromQL 查詢及繪製下列來源的 Cloud Monitoring 資料：
- Google Cloud 服務，例如 Google Kubernetes Engine 或 Compute Engine，這些服務會寫入Cloud Monitoring 系統指標清單中說明的指標。
- 使用者定義的指標，例如記錄指標和 Cloud Monitoring 使用者定義的指標。
- Google Cloud Managed Service for Prometheus 是Google Cloud推出的全代管多雲解決方案，適用於 Prometheus。如要瞭解這項代管服務 (包括 PromQL 支援)，請參閱「Google Cloud Managed Service for Prometheus」。
您也可以使用 Grafana 等工具，繪製擷取到 Cloud Monitoring 的指標資料圖表。可用指標包括 Managed Service for Prometheus 指標，以及指標清單中記錄的 Cloud Monitoring 指標。如要瞭解如何根據 Prometheus API 設定 Grafana 和其他工具，請參閱 Managed Service for Prometheus 說明文件中的 Grafana。
您也可以將 Grafana 資訊主頁匯入 Cloud Monitoring。
使用 PromQL 查詢 Cloud Monitoring 指標
您可以使用 PromQL 的 UTF-8 規格查詢 Cloud Monitoring 指標。UTF-8 指標名稱必須加上引號，並移至大括號內。如果標籤名稱包含不相容於舊版的字元，也必須加上引號。如果是 Cloud Monitoring 指標
kubernetes.io/container/cpu/limit_utilization，下列查詢是等效的：
{"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}{__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}。{"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}。
您可以查詢 Cloud Monitoring 分配值指標，就像查詢 Prometheus 直方圖一樣，只要在指標名稱後方加上 _count、_sum 或 _bucket 後置字元即可。
您可以在 PromQL 中使用中繼資料標籤，就像使用任何其他標籤一樣，但與指標名稱類似，中繼資料標籤也必須與 PromQL 相容。如要參照中繼資料系統標籤 version，請使用 metadata_system_version 語法；如要參照中繼資料使用者標籤 version，請使用 metadata_user_version 語法。使用中繼資料標籤的格式正確 PromQL 查詢可能如下所示：
{"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env){"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")
如果您的中繼資料標籤鍵包含 _ 以外的特殊字元，則必須根據 PromQL 的 UTF-8 規格，將標籤鍵括在雙引號 (") 中。
您仍須在元資料標籤加上 metadata_user_ 字串前置字元。
如果圖表和資訊主頁是在 UTF-8 相容性查詢之前建立，系統會將這些圖表和資訊主頁的名稱轉換為舊版 PromQL 相容的對應名稱，然後查詢 Cloud Monitoring 指標。如要進一步瞭解舊版 PromQL 轉換規則，請參閱「將 Cloud Monitoring 指標對應至舊版 PromQL」。
在 Cloud Monitoring 中存取 PromQL
您可以在 Google Cloud 控制台的下列頁面，透過「程式碼」分頁使用 PromQL：
- Metrics Explorer
- 建立自訂資訊主頁時新增圖表
如要瞭解如何存取及使用編輯器，請參閱「使用 PromQL 編輯器」。
PromQL 規則和快訊
您可以使用 PromQL，為 Cloud Monitoring 中的任何指標建立快訊政策。詳情請參閱「以 PromQL 為基礎的快訊政策」。
您也可以使用 PromQL，透過 Cloud Monitoring 中的 Prometheus 樣式叢集內快訊，在 Cloud Monitoring 中對任何指標建立記錄和快訊規則。詳情請參閱「受管理規則評估和快訊」或「自行部署的規則評估和快訊」。
學習 PromQL
如要瞭解 PromQL 的基本用法，建議參閱開放原始碼文件。如要開始使用，請參閱下列資源：
指定受監控的資源類型
如果 Cloud Monitoring 指標只與單一Cloud Monitoring 受監控資源類型相關聯，PromQL 查詢就會正常運作，無需手動指定資源類型。不過，Cloud Monitoring 中的部分指標 (包括某些系統指標，以及許多由以記錄為準的指標產生的指標)，會對應至多個資源類型。如果您使用其中一項指標 (尤其是記錄指標)，則必須明確指定資源類型。如要查看哪些受控資源類型對應至指標，請執行下列任一操作：
- 如要查看 Google 製作的指標，請參閱可用指標清單，包括 Google Cloud指標和 Kubernetes 指標。說明文件中的每個項目都會在類型下方的第一欄列出相關聯的受監控資源類型。如果沒有列出受監控的資源類型，指標可以與任何類型建立關聯。
在 Metrics Explorer 中，您可以執行下列操作：
- 在「選取指標」欄位中輸入指標名稱，然後瀏覽選單來選取指標。資源選單會列出該指標的有效資源類型，例如「VM 執行個體」。
在查詢建構工具窗格的工具列中，選取名稱為「< > PromQL」的按鈕。
顯示的 PromQL 查詢會將資源類型做為
monitored_resource欄位的值。特別是對於可與多種受監控資源類型建立關聯的指標 (例如記錄指標、自訂指標或任何使用者定義的指標)，這個方法非常實用。
如果指標與多個資源類型相關聯，您必須在 PromQL 查詢中指定資源類型。您可以使用特殊標籤 monitored_resource 選取資源類型。
受控資源類型通常是短字串，例如 gce_instance，但有時會顯示為完整 URI，例如 monitoring.googleapis.com/MetricIngestionAttribution。格式正確的 PromQL 查詢可能如下所示：
logging_googleapis_com:byte_count{monitored_resource="k8s_container"}custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}
monitored_resource 標籤的 "" 值很特別，是指用於 Cloud Monitoring 指標的預設 prometheus_target 資源類型。
如果未在必要時使用 monitored_resource 標籤，系統會顯示下列錯誤訊息：
metric is configured to be used with more than one monitored resource type;
series selector must specify a label matcher on monitored resource name
解決標籤衝突
在 Cloud Monitoring 中，標籤可以屬於指標或資源。如果指標標籤與資源標籤的鍵名相同，您可以在查詢中將前置字元 metric_ 加入標籤鍵名，即可專指指標標籤。
舉例來說，假設您在指標 example.googleapis.com/user/widget_count 中，同時有資源標籤和指標標籤都命名為 pod_name。
如要依資源標籤的值篩選，請使用
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}如要依指標標籤的值篩選，請使用
example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}
將 Cloud Monitoring 指標名稱對應至舊版 PromQL
Cloud Monitoring 指標名稱包含兩個元件：網域 (例如 compute.googleapis.com/) 和路徑 (例如 instance/disk/max_read_ops_count)。由於舊版 PromQL 只支援特殊字元 : 和 _，因此您必須套用下列規則，才能讓 Monitoring 指標名稱與舊版 PromQL 相容：
- 將第一個
/替換為:。 - 將所有其他特殊字元 (包括
.和其他/字元) 替換為_。
下表列出部分指標名稱和對應的舊版 PromQL：
| Cloud Monitoring 指標名稱 | 舊版 PromQL 指標名稱 |
|---|---|
kubernetes.io/container/cpu/limit_cores |
kubernetes_io:container_cpu_limit_cores |
compute.googleapis.com/instance/cpu/utilization |
compute_googleapis_com:instance_cpu_utilization |
logging.googleapis.com/log_entry_count |
logging_googleapis_com:log_entry_count |
custom.googleapis.com/opencensus/opencensus.io/ |
custom_googleapis_com:opencensus_opencensus_io_ |
agent.googleapis.com/disk/io_time |
agent_googleapis_com:disk_io_time |
您可以查詢 Cloud Monitoring 分配值指標，就像查詢 Prometheus 直方圖一樣，只要在指標名稱後方加上 _count、_sum 或 _bucket 後置字元即可：
| Cloud Monitoring 指標名稱 | 舊版 PromQL 指標名稱 |
|---|---|
networking.googleapis.com/vm_flow/rtt |
networking_googleapis_com:vm_flow_rtt_sumnetworking_googleapis_com:vm_flow_rtt_countnetworking_googleapis_com:vm_flow_rtt_bucket
|
PromQL 相容性
Cloud Monitoring 的 PromQL 可能與上游 PromQL 的運作方式略有不同。
Cloud Monitoring 中的 PromQL 查詢會在 Monarch 後端使用內部查詢語言進行部分評估，因此查詢結果會出現一些已知差異。除了本節列出的差異之外，Cloud Monitoring 中的 PromQL 與 Prometheus 2.44 版的 PromQL 相同。系統可能不支援 Prometheus 2.44 版之後新增的 PromQL 函式。
支援 UTF-8
Cloud Monitoring 的 PromQL 支援 UTF-8 查詢。
如果 Prometheus 指標名稱只包含英數字元和 _ 或 : 字元，且標籤鍵只包含英數字元和 _ 字元，您就可以使用傳統的 PromQL 語法查詢。舉例來說，有效的查詢可能如下所示：
job:my_metric:sum{label_key="label_value"}。
不過，如果 Prometheus 指標名稱使用 _ 或 : 以外的任何特殊字元，或是標籤鍵使用 _ 以外的任何特殊字元，則必須根據 PromQL 的 UTF-8 規格建構查詢。
UTF-8 指標名稱必須加上引號，並移至大括號內。如果標籤名稱含有不相容的舊版字元，也必須加上引號。以下有效查詢範例皆相等：
{"my.domain.com/metric/name_bucket", "label.key"="label.value"}{__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}{"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}
依指標名稱比對
系統只支援完全比對指標名稱。查詢中必須包含完全相符的指標名稱。
如果常見情境在 __name__ 標籤上使用規則運算式比對器，建議您採取下列因應措施：
- Prometheus 介面卡設定通常會使用
=~運算子，比對多個指標名稱。如要修正這項用法，請展開設定，為每項指標使用個別政策，並明確命名每項指標。這也能避免您根據非預期的指標，意外自動調度資源。 - 您通常會使用規則運算式，在同一張圖表上繪製多個非維度指標的圖表。舉例來說，如果您有
cpu_servicename_usage這類指標，可以使用萬用字元將所有服務繪製在同一張圖表上。在 Cloud Monitoring 中，使用這類非維度指標是明顯的錯誤做法，而且會導致查詢效能極差。如要修正這項用量，請將所有維度移至指標標籤，而非將維度嵌入指標名稱。 - 查詢多個指標通常是用來查看可查詢的指標。建議您改用
/labels/__name__/values呼叫來探索指標。您也可以使用 Cloud Monitoring UI 探索指標。 - 比對多個指標有助於瞭解每個指標的擷取、擷取和計費樣本數。Cloud Monitoring 會在「指標管理」頁面提供這項資訊。您也可以使用擷取的樣本指標或依歸因 ID 寫入的樣本指標，以指標資料的形式存取這項資訊。
過時程度
Monarch 後端不支援過時。
計算 irate
如果 irate 函式的回溯期小於步長，我們會將回溯期增加至步長。Monarch 需要這項變更，確保輸出內容不會完全忽略任何輸入資料。這項差異也適用於 rate 計算。
rate 和 increase 的計算方式
如果 rate 函式的回溯期小於步長，我們會將回溯期增加至步長。Monarch 需要這項變更，確保輸出內容不會完全忽略任何輸入資料。這項差異也適用於 irate 計算。
內插法和外插法的計算方式不同。 Monarch 使用的插補演算法與 Prometheus 不同，因此結果可能略有差異。舉例來說，Monarch 計數器樣本會連同時間範圍一併儲存，而非 Prometheus 使用的單一時間戳記。因此，即使 Prometheus 時間戳記會排除這些樣本，Monarch 仍可將計數器樣本納入速率計算。這通常會產生更準確的費率結果，尤其是在查詢基礎時間序列的開頭或結尾時。
計算 histogram_quantile
如果直方圖沒有樣本，PromQL histogram_quantile 計算會產生 NaN 值。內部查詢語言的計算不會產生任何值，而是會捨棄時間戳記的點。
費率計算差異也可能影響 histogram_quantile 查詢的輸入內容。
不同類型指標的類型專屬函式
雖然上游 Prometheus 是弱型別，但 Monarch 是強型別。也就是說，在 Cloud Monitoring 中，針對不同類型的指標執行特定類型的函式 (例如對 GAUGE 指標執行 rate()，或對 COUNTER 或未輸入類型的指標執行 histogram_quantile()) 無效，即使這些函式在上游 Prometheus 中有效也一樣。