本頁面由 Cloud Translation API 翻譯而成。

查詢及查看指標

從 Google Distributed Cloud (GDC) 氣隙環境中部署的工作負載收集指標後，即可開始分析。如要分析指標，您可以在資訊豐富的 Grafana 資訊主頁上以視覺化方式呈現及篩選指標，也可以使用 curl 工具直接從 Cortex 存取指標，以便彈性編寫指令碼及自動化。

本頁提供詳細操作說明，介紹如何使用 Grafana 使用者介面和 Cortex 端點的 curl 工具查詢及顯示指標，進而深入瞭解工作負載效能。

您可以透過下列兩種方式存取指標：

Grafana 資訊主頁：透過 CPU 使用率、儲存空間用量和網路活動等重要指標的直覺式視覺化呈現方式，探索趨勢並找出異常情況。Grafana 提供簡單易用的介面，方便您在資訊主頁中篩選及分析工作負載資料。
Cortex 端點：如要進行更進階的用途，請使用指令列上的 curl 工具，直接查詢專案的 Cortex 執行個體。Cortex 會儲存專案的 Prometheus 指標，並提供 HTTP 端點供程式存取。您可透過這項存取權匯出資料、自動執行工作，以及建構自訂整合功能。

事前準備

如要取得在 Grafana 資訊主頁上查詢及顯示指標所需的權限，請要求機構 IAM 管理員或專案 IAM 管理員授予您預先定義的機構 Grafana 檢視者或專案 Grafana 檢視者角色。視您需要的存取層級和權限而定，您可能需要取得機構或專案的 Grafana 角色。

或者，如要取得從 Cortex 端點查詢指標所需的權限，請要求專案 IAM 管理員在專案命名空間中，授予您專案 Cortex Prometheus 檢視者角色。

下表摘要說明 PA persona 的 Role 規定。

角色	物件	叢集	角色	命名空間	群組/使用者	設定
PA	grafana	org-admin	`project-grafana-viewer`	platform-obs	群組	1
PA	cortex	org-admin	`project-cortex-prometheus-viewer`	platform-obs	群組	2
PA	grafana	org-admin	`project-grafana-viewer`	platform-obs	使用者	3
PA	cortex	org-admin	`project-cortex-prometheus-viewer`	platform-obs	使用者	4

請適當替換下列變數：

變數	說明
`KUBECONFIG`	您需要特定叢集的 kubeconfig，其中包含要套用 RoleBinding 的 `NAMESPACE`。
`RULE_NAME`	命名空間中這個 `RoleBinding` 資源的專屬名稱。例如：`io-root-cortex-prometheus-viewer`。
`NAMESPACE`	要建立及套用此 `RoleBinding` 的 Kubernetes 命名空間。在先前的表格中尋找「`Namespace`」欄。
`EMAIL_ADDRESS`	獲派角色的使用者 ID。這通常是電子郵件地址。例如 `infrastructure-operator@example.com`。
`ROLE`	`Role` 的名稱，其中包含您要授予使用者的權限。尋找上表列出的可用角色
`GROUP_NAME`	`Role` 的名稱，其中包含您要授予使用者的權限。例如：`io-group`。
`ZONE`	區域名稱

設定 1

這項設定適用於 PA 角色，目標是 org-admin 叢集中的 grafana 物件。將 platform-obs 命名空間中的 project-grafana-viewer 角色授予 Group。

kubectl 指令

一般指令格式如下：

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer

範例：

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

IAC 檔案路徑

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

Yaml 檔案

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

設定 2

這項設定適用於 PA 角色，目標是 org-admin 叢集中的 cortex 物件。將 platform-obs 命名空間中的 project-cortex-prometheus-viewer 角色授予 Group。

kubectl 指令

一般指令格式如下：

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer

範例：

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs

IAC 檔案路徑

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

Yaml 檔案

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

設定 3

這項設定適用於 PA 角色，目標是 org-admin 叢集中的 grafana 物件。將 platform-obs 命名空間中的 project-grafana-viewer 角色授予 User。

kubectl 指令

一般指令格式如下：

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer

範例：

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

IAC 檔案路徑

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

Yaml 檔案

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

設定 4

這項設定適用於 PA 角色，目標是 org-admin 叢集中的 cortex 物件。將 platform-obs 命名空間中的 project-cortex-prometheus-viewer 角色授予 User。

kubectl 指令

一般指令格式如下：

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer

範例：

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obs

IAC 檔案路徑

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

Yaml 檔案

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

如要進一步瞭解這些角色，請參閱「準備 IAM 權限」。

取得及篩選指標

選取下列其中一種方法，即可建構查詢、以圖表呈現趨勢，以及從專案工作負載中篩選指標：

Grafana 資訊主頁

本節說明如何使用 Grafana 資訊主頁存取指標。

找出 Grafana 端點

以下網址是專案 Grafana 執行個體的端點：

  https://GDC_URL/PROJECT_NAMESPACE/grafana

更改下列內容：

GDC_URL：您在 GDC 中的機構網址。
PROJECT_NAMESPACE：您的專案命名空間。

舉例來說，org-1 機構中 platform-obs 專案的 Grafana 端點為 https://org-1/platform-obs/grafana。

在 Grafana 使用者介面中查看指標

在 Grafana 使用者介面中擷取指標：

在 GDC 控制台中選取專案。
在導覽選單中，依序選取「Operations」>「Monitoring」。
按一下「在 Grafana 中查看所有項目」。

新頁面會開啟 Grafana 端點，並顯示使用者介面。
在使用者介面中，按一下導覽選單中的「探索」，開啟「探索」頁面。
在「探索」列的選單中，根據您的宇宙類型選取資料來源，以擷取指標：
- 單一可用區的宇宙：選取「prometheus」，即可顯示宇宙單一可用區的指標。
- 多區域宇宙：Grafana 可以連線至不同區域，並顯示跨區域資料。選取「指標」ZONE_NAME，即可顯示宇宙中任何區域的指標，不論您登入的區域為何。
  
  此外，如要在單一資訊主頁中顯示跨區域資料，並在查詢中新增多個區域，請選取「混合」做為資料來源。
輸入查詢，使用 PromQL (Prometheus 查詢語言) 運算式搜尋指標。您可以選擇下列任一方式完成這個步驟：
- 從「指標」和「標籤篩選器」選單中，選取查詢的指標和標籤。按一下「新增」，即可在查詢中新增更多標籤。然後按一下「執行查詢」。
- 直接在「指標」文字欄位中輸入查詢，然後按下 Shift+Enter 鍵執行查詢。
頁面會顯示符合查詢條件的指標。

圖 1. 從 Grafana 使用者介面查詢指標的選單選項。

如圖 1 所示，選取「prometheus」選項後，系統會顯示介面，讓您從 Grafana 建立查詢來擷取指標。

如需可用於查詢指標的標籤值示例，請參閱範例查詢和標籤。

Cortex 端點

本節說明如何使用 Cortex 存取指標。

找出 Cortex 端點

以下網址是專案 Cortex 執行個體的端點：

  https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/

更改下列內容：

GDC_URL：您在 GDC 中的機構網址。
PROJECT_NAMESPACE：您的專案命名空間。

舉例來說，org-1 機構中 platform-obs 專案的 Cortex 端點是 https://org-1/platform-obs/cortex/prometheus/。

注意： 您可以在網路瀏覽器中直接開啟網址，查詢指標。下列各節的指示會使用 curl 指令呼叫端點，但這也適用於網頁瀏覽器。

驗證 `curl` 要求

下載並安裝 gdcloud CLI。

設定 gdcloud core/organization_console_url 屬性：

gdcloud config set core/organization_console_url
https://GDC_URL

使用已設定的識別資訊提供者登入：
```
gdcloud auth login
```
使用使用者名稱和密碼進行驗證並登入。

登入成功後，您可以使用 gdcloud auth print-identity-token 指令，在 curl 要求中加入授權標頭。詳情請參閱 gcloud auth。

呼叫 Cortex 端點

請完成下列步驟，使用 curl 工具連上 Cortex 端點：

驗證 curl 要求。
使用 curl 呼叫 Cortex 端點，並使用 Querying HTTP API Format 擴充網址，以查詢指標。

以下是 curl 要求範例：
```
curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"
```
執行指令後，您會取得輸出內容。API 回應採用 JSON 格式。

注意： 在網址中加入 api/v1/query 端點，即可查詢指標。您可以在網址結尾的問號 (?) 後方，加入 API 呼叫的選用參數。請以連字號 (&) 符號分隔這些參數，如上一個步驟的 curl 要求範例所示。

查詢和標籤範例

您可以透過指標名稱和標籤的鍵/值組合查詢指標。PromQL 查詢的語法如下：

metric_name{label_one="value", label_two="value"}

標籤可讓您區分指標的特徵。這樣一來，容器作者就能讓工作負載產生指標，並新增標記來篩選這些指標。

舉例來說，您可以建立 api_http_requests_total 指標，計算收到的 HTTP 要求數量。然後，您可以在這項指標上新增 request_method 標籤，該標籤會採用 POST、GET 或 PUT 值。因此，您會為可能收到的每種要求類型建立三個指標串流。在本例中，如要找出 HTTP GET 要求數量，請執行下列查詢：

api_http_requests_total{request_method="GET"}

如要進一步瞭解指標和標籤，請參閱「指標和標籤命名」。

以下是 MonitoringTarget 自訂資源新增的部分預設標籤。您可以使用這些預設標籤查詢指標：

_gdch_service：服務的簡短名稱。
cluster：叢集名稱。
container_name：Pod 內的容器名稱。
namespace_name：您的專案命名空間。
pod_name：Pod 名稱前置字串。

下表說明 Prometheus 自動新增的標籤：

預設標籤
指標標籤	說明
`job`	用於收集指標的擷取工作內部名稱。由 `MonitoringTarget` 自訂資源建立的工作名稱會採用下列模式： `obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/J` `I` 和 `J` 是內部決定的專屬號碼，可避免名稱衝突。
`instance`	報廢服務的 `$IP:$PORT`。如果工作負載資源有多個副本，請使用這個欄位加以區分。

下列程式碼範例顯示如何使用標籤的鍵/值組合查詢不同指標：

查看專案中已處理作業的所有指標串流：
```
processed_ops_total
```
查看 Kubernetes 叢集中收集的已處理作業：
```
processed_ops_total{cluster="CLUSTER_NAME"}
```
查看 Kubernetes 叢集中收集的 CPU 用量：
```
cpu_usage{cluster="CLUSTER_NAME"}
```

使用指標重新標記工具，新增最初未由擷取的容器公開的標籤，並重新命名產生的指標。您必須設定 MonitoringTarget 自訂資源，才能在收集的指標上新增標籤。在自訂資源的 metricsRelabelings 欄位中指定這些標籤。詳情請參閱「標籤指標」。

查詢 HTTP API

格式總覽

API 回應一律採用 JSON 格式。成功的要求一律會收到 2xx 狀態碼。

如果要求無效，API 處理常式會傳回 JSON 錯誤物件，以及下列其中一個 HTTP 狀態碼：

400 Bad Request：如果缺少必要參數或參數提供有誤。
503 Service Unavailable：如果查詢超過時間限制或遭到中止。

成功收集到的所有資料都會納入回應的「data」欄位。

JSON 回應封包格式如下：

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

即時查詢

下列端點會評估單一時間點的即時查詢：

GET /api/v1/query
POST /api/v1/query

Prometheus 運算式查詢可使用下列網址查詢參數：

query=<string>：Prometheus 運算式查詢字串。
time=<rfc3339 | unix_timestamp>：選用的評估時間戳記，以 RFC 3339 字串或 Unix 時間戳記指定。如果省略此值，系統會使用目前的伺服器時間。
timeout=<duration>：選用的評估逾時時間。預設值為 query.timeout 標記的值，且受該值限制。
limit=<number>：(選填) 要傳回的數列數量上限。這會截斷矩陣和向量的序列，但不會影響純量或字串。如果值為 0，表示停用這項限制。
lookback_delta=<number>：選用參數，可專門針對這項查詢覆寫回溯期。

如果省略時間參數，系統會使用目前的伺服器時間。

如果查詢較大，可能會超出網址字元限制，您可以使用 POST 方法提交這些參數。確認要求主體已採用 URL 編碼，且 Content-Type 標頭已設為 application/x-www-form-urlencoded。

查詢結果的資料部分格式如下：

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> 是指查詢結果資料，格式會因 resultType 而異。

以下範例會在 2015 年 7 月 1 日下午 8:10:51.781 (UTC) 評估 up 運算式：

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

範圍查詢

下列端點會評估一段時間範圍內的運算式查詢：

GET /api/v1/query_range
POST /api/v1/query_range

Prometheus 運算式查詢可使用下列網址查詢參數：

query=<string>：Prometheus 運算式查詢字串。
start=<rfc3339 | unix_timestamp>：開始時間戳記 (含)。
end=<rfc3339 | unix_timestamp>：結束時間戳記 (含)。
step=<duration | float>：查詢解析度步幅，格式為時間長度或浮點數 (以秒為單位)。
timeout=<duration>：選用的評估逾時時間。預設值為 query.timeout 標記的值，且受該值限制。
limit=<number>：(選填) 要傳回的數列數量上限。這會截斷矩陣和向量的序列，但不會影響純量或字串。如果值為 0，表示停用這項限制。
lookback_delta=<number>：選用參數，可專門針對這項查詢覆寫回溯期。

查詢結果的資料部分格式如下：

{
  "resultType": "matrix",
  "result": <value>
}

以下範例會評估 30 秒範圍內的 up 運算式，查詢解析度為 15 秒。

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

指標和標籤命名

指標命名規範

定義指標名稱時，請考量下列原則：

指標名稱「應」包含單字應用程式前置字串，用戶端程式庫有時會將其稱為「命名空間」。這個前置字元會識別指標所屬的網域。如果是特定應用程式的指標，通常會使用應用程式名稱做為前置字串。

範例：
- prometheus_notifications_total (Prometheus 伺服器專用)
- process_cpu_seconds_total (由許多用戶端程式庫匯出)
- http_request_duration_seconds (適用於所有 HTTP 要求)
指標名稱必須代表單一單位 (例如，請勿混用秒和毫秒，或秒和位元組)。
指標名稱「應」使用基本單位 (例如秒、位元組、公尺)，而非衍生單位 (例如毫秒、MB、公里)。
指標名稱「應」包含複數單位後置字串。如要累計計數，請視情況在單位後方加上「total」後置字元。

範例：
- http_request_duration_seconds
- node_memory_usage_bytes
- http_requests_total (用於無單位的累計計數)
- process_cpu_seconds_total (用於累積計數，附帶單位)
- foobar_build_info (用於提供執行中二進位檔相關中繼資料的虛擬指標)
指標名稱可排序其元件，方便依字典順序排序時進行分組，但前提是必須遵守所有其他規則。相關指標通常會先放置通用名稱元件，確保這些指標會一起排序。

範例：
- prometheus_tsdb_head_truncations_closed_total
- prometheus_tsdb_head_truncations_established_total
- prometheus_tsdb_head_truncations_failed_total
- prometheus_tsdb_head_truncations_total
指標名稱「應」在所有標籤維度中，一致代表相同的邏輯「測量對象」。

範例：
- 要求持續時間
- 資料傳輸位元組數
- 即時資源用量百分比

標籤命名規範

測量某個項目時，請使用標籤區分其特徵。例如：

如要查看 API HTTP 要求的總數 (api_http_requests_total)，請依作業類型區分，例如 create、update、delete (要求類型：operation="create|update|delete")。
以秒為單位 (api_request_duration_seconds) 計算 API 要求時間長度時，請依要求階段區分，例如 extract、transform、load (要求階段：stage="extract|transform|load")。

請避免在指標名稱中加入標籤名稱，因為這樣會造成多餘資訊，且如果這些標籤稍後經過彙整，可能會導致混淆。

查詢及查看指標 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定 1

設定 2

設定 3

設定 4

取得及篩選指標

Grafana 資訊主頁

找出 Grafana 端點

在 Grafana 使用者介面中查看指標

Cortex 端點

找出 Cortex 端點

驗證 curl 要求

呼叫 Cortex 端點

查詢和標籤範例

查詢 HTTP API

格式總覽

即時查詢

範圍查詢

指標和標籤命名

指標命名規範

標籤命名規範

查詢及查看指標

驗證 `curl` 要求