查詢及查看指標

從 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 專案管理員在專案命名空間中，授予您 Project Cortex Prometheus 檢視者角色。

下表摘要列出 PA 和 AO 角色對 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
AO grafana org-admin project-grafana-viewer PROJECT_NAMESPACE 群組 1
AO cortex org-admin project-cortex-prometheus-viewer PROJECT_NAMESPACE 群組 2
AO grafana org-admin project-grafana-viewer PROJECT_NAMESPACE 使用者 3
AO cortex org-admin project-cortex-prometheus-viewer PROJECT_NAMESPACE 使用者 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 PA/AO 使用者所屬的Group名稱。例如：pa-group。
ZONE 可用區名稱

設定 1

這項設定會授予使用者群組權限，允許存取 org 叢集中的 PA/AO Grafana。完成這項設定後，請參閱本文的「Grafana 資訊主頁」一節，瞭解如何在 Grafana 查看指標。

  • 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

這項設定會將權限授予使用者群組，讓他們能以程式輔助方式存取 org 叢集中的 PA/AO 指標。完成這項設定後，請參閱本文的「Cortex 端點」一節，瞭解如何透過程式輔助方式查詢指標。

  • 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

這項設定會授予使用者權限，允許他們存取 org 叢集中的 PA/AO Grafana。完成這項設定後，請參閱本文的「Grafana 資訊主頁」一節，瞭解如何在 Grafana 查看指標。

  • 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

這項設定會授予使用者權限，讓他們能以程式輔助方式存取 org 叢集中的 PA/AO 指標。完成這項設定後，請參閱本文的「Cortex 端點」一節，瞭解如何透過程式輔助方式查詢指標。

  • 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 使用者介面中擷取指標：

  1. 在 GDC 控制台中選取專案。
  2. 在導覽選單中，依序選取「Operations」>「Monitoring」。

  3. 按一下「View all in Grafana」(在 Grafana 中查看全部)。

    新頁面會開啟 Grafana 端點並顯示使用者介面。

  4. 在使用者介面中，按一下導覽選單中的「探索」，開啟「探索」頁面。

  5. 在「Explore」(探索) 列的選單中，根據母體類型選取資料來源，擷取指標：

    • 單一可用區宇宙：選取「prometheus」，即可顯示宇宙中單一可用區的指標。

    • 多可用區宇宙：Grafana 可連結至不同可用區，並顯示跨可用區資料。選取「Metrics」(指標) ZONE_NAME，即可顯示宇宙中任何區域的指標，無論您登入的是哪個區域。

      此外，如要在單一資訊主頁中跨可用區以圖表呈現資料，並在查詢中新增多個可用區，請選取「Mixed」(混合) 做為資料來源。

  6. 輸入查詢，使用 PromQL (Prometheus 查詢語言) 運算式搜尋指標。您可以透過下列任一方式執行這個步驟：

    • 從「Metric」(指標) 和「Label filters」(標籤篩選器) 選單中，選取查詢的指標和標籤。按一下「add」(新增) ，為查詢新增更多標籤。接著點選「執行查詢」。
    • 直接在「Metrics」(指標) 文字欄位中輸入查詢，然後按下 Shift+Enter 鍵執行查詢。

    頁面會顯示符合查詢的指標。

    在「探索」頁面選取「prometheus」選項，即可取得指標。

    圖 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 要求

  1. 下載並安裝 gdcloud CLI。

  2. 設定 gdcloud core/organization_console_url 屬性：

    gdcloud config set core/organization_console_url
https://GDC_URL

  3. 使用設定的識別資訊提供者登入：

    gdcloud auth login

  4. 使用使用者名稱和密碼驗證身分並登入。

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

呼叫 Cortex 端點

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

  1. 驗證 curl 要求。

  2. 使用 curl 呼叫 Cortex 端點，並使用查詢 HTTP API 格式擴充網址，以查詢指標。

    以下是 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 格式呈現。

Cortex 端點 - 多可用區

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

找出 Cortex 端點

下列網址是專案 Cortex 執行個體的端點，用於多可用區查詢：

  https://GDC_URL/PROJECT_NAMESPACE/cortex/metrics

更改下列內容：

  • GDC_URL：組織在 GDC 中的網址。

    • org-1、zone1 的範例：console.org-1.zone1.google.gdch.test
    • 替換應用程式的組織和可用區。

  • PROJECT_NAMESPACE：專案命名空間。

    舉例來說，org-1 組織中 project-1 專案的 Cortex 端點為 https://console.org-1.zone1.google.gdch.test/project-1/cortex/metrics.。

驗證 curl 要求

  1. 下載並安裝 gdcloud CLI。

  2. 設定 gdcloud core/organization_console_url 屬性：

    gdcloud config set core/organization_console_url
https://GDC_URL

  3. 使用設定的識別資訊提供者登入：

    gdcloud auth login

  4. 使用使用者名稱和密碼驗證身分並登入。

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

呼叫 Cortex 端點

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

  1. 驗證 curl 要求。
  2. 使用 curl 呼叫 Cortex 端點，並使用查詢 HTTP API 格式擴充網址，以查詢指標。

  3. 除了 Prometheus 網址查詢參數外，請加入位置參數，提供要查詢的可用區清單。- location={string}：以 | 分隔的可用區清單 - 如未提供，系統會在所有可用區執行查詢。

    以下是 curl POST 要求範例：

     curl POST \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range" \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query=pod_cpu_usage_total' \
--data-urlencode 'start=2025-07-21T16:00:00Z' \
--data-urlencode 'end=2025-07-21T16:15:00Z' \
--data-urlencode 'step=60s' \
--data-urlencode 'location=zone1|zone2' \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"

    以下是 curl GET 要求範例：

     curl -X GET \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range?query=pod_cpu_usage_total&start=2025-07-21T16:00:00Z&end=2025-07-21T16:15:00Z&step=1s&location=zone1|zone2" \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"

    執行指令後，您會取得輸出內容。API 回應會以 JSON 格式呈現。

查詢和標籤範例

您可以使用指標名稱和標籤的鍵/值組合，查詢指標。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。如果工作負載資源有多個副本，請使用這個欄位加以區分。

下列程式碼範例顯示如何使用標籤的鍵/值組合查詢不同指標，查看在 Kubernetes 叢集中收集的 CPU 使用率：

pod_cpu_usage_total{cluster="CLUSTER_NAME"}

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

以下是從 Cortex 指標端點收到的回應範例：

          {
    "zone1": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.192.1.74:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-swzgq",
              "zone_id": "zone1"
            },
            "values": [
              [
                1753261200,
                "2.258621991"
              ],
              [
                1753261800,
                "1.029301454"
              ]
            ]
          }
        ]
      }
    },
    "zone2": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.196.3.208:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-kchfv",
              "zone_id": "zone2"
            },
            "values": [
              [
                1753261200,
                "1.814027424"
              ],
              [
                1753261800,
                "2.7767060260000003"
              ]
            ]
          }
        ]
      }
    }
  }

查詢 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 方法提交這些參數。確認要求主體已進行網址編碼，且 Content-Type 標頭設為 application/x-www-form-urlencoded。

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

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

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

以下範例會評估 2015-07-01T20:10:51.781Z 的運算式：

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>：選用參數，可覆寫這項查詢的回溯期。

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

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

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

以下範例會評估 30 秒範圍內的運算式，查詢解析度為 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")。

請避免在指標名稱中加入標籤名稱，以免造成重複，並在日後匯總這些標籤時造成混淆。