設定記錄指標的標籤

本文將說明記錄指標標籤，並說明如何建立及使用記錄指標標籤。

如果您熟悉標籤，可以直接前往本頁的「建立標籤」一節。

記錄指標標籤總覽

標籤可讓記錄指標包含多個時間序列，每個標籤值組合對應一個時間序列。所有記錄指標都隨附一些預設標籤。

您可以指定擷取器運算式，以在計數器類型及分佈類型指標中建立其他使用者定義的標籤。擷取器運算式會告訴 Cloud Logging 如何從記錄項目中擷取標籤的值。您可以指定下列任一標籤值：

• LogEntry 物件中指定名稱欄位的完整內容。
• 符合規則運算式 (regexp) 的命名欄位部分。

您可以從 LogEntry 內建欄位 (例如 httpRequest.status) 或其中一個酬載欄位 textPayload、jsonPayload 或 protoPayload 中擷取標籤。

如要瞭解規則運算式，請參閱 RE2 語法。

請勿在擷取器運算式中加入機密資訊，也不要將機密資料擷取到標籤中。這些資料會視為服務資料。

使用者定義標籤的限制

使用者定義的標籤有以下限制：

• 您最多可為每個指標建立 10 個使用者定義的標籤。

• 建立標籤後，就無法刪除。

  • 如果是您已建立的標籤，您就可以修改標籤的擷取器運算式與說明。

  • 您無法變更已建立之標籤的名稱或值類型。

• 系統只會保留標籤值的前 1,024 個字元。

• 每個記錄指標都受限於約 30,000 個有效時間序列，這取決於每個標籤的可能值數目，包括預設標籤在內。

  舉例來說，如果您的記錄項目來自 100 項資源 (例如 VM 執行個體)，且您為標籤定義了 20 種可能的值，則您的指標最多可能會有 2,000 個時間序列。

如果您的時間序列數或資料點數太多，您的成本將會上升，您的活動也可能會受到限制。如要進一步瞭解以記錄為基礎的指標費用，請參閱「Cloud Monitoring 定價：可收費指標」。如要瞭解記錄指標的限制，請參閱「配額和限制：記錄指標」和「排解記錄指標問題」。

預設標籤

大多數的記錄指標都隨附一些預先定義的標籤：

• 資源標籤：所有指標都使用受控資源物件來識別時間序列資料的來源。每個資源類型都包含類型名稱與一或多個標籤。資源類型範例包括 VM 執行個體、Cloud SQL 資料庫和負載平衡器。

  在 Cloud Monitoring 中，資源及其標籤會與其他指標標籤分開列出，但它們的效果是相同的：它們都會在指標中建立額外的時間序列。詳情請參閱指標、時間序列和資源一文。

• log (記錄)：此標籤可在記錄項目中保存 logName 欄位 LOG_ID 部分的值。

• severity (嚴重性)：此標籤可在記錄項目中保存 severity 欄位的值。根據預設，嚴重性標籤只會在系統記錄指標中提供。

使用 Metrics Explorer 查看標籤

如要查看為記錄指標產生的時間序列上的標籤，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Log-based Metrics」(記錄指標) 頁面：

   前往「記錄指標」

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 尋找要查看的指標，然後在指標的 more_vert「更多」選單中選取「在 Metrics Explorer 中查看」。

   繼續操作前，請等待圖表顯示資料，如果您建立的是以記錄檔為基礎的指標，可能需要等待幾分鐘。

3. 如要查看可用的標籤，請展開「Filter」欄位。您可能會看到資源標籤和指標標籤。標籤清單會依資源類型和指標類型而異。例如：

   • gce_instance 資源類型有三個資源標籤：project_id、instance_id 和 zone。

   • logging/log_entry_count 指標類型有兩個指標標籤：log 和 severity。您的使用者定義標籤也會顯示在此部分。

4. 如要確認使用者定義的標籤是否從記錄項目中擷取正確資料，請按照下列步驟操作：

   1. 將「Aggregation」元素變更為「Unaggregated」。

   2. 在圖表中選取「表格」或「兩者皆是」。

   3. 在工具列中，選取 view_column「資料欄顯示選單」，然後選取標籤。這個選單會顯示所有含有資料的標籤。

      如果沒有看到您建立的標籤，請確認欄位名稱和擷取器運算式。

建立標籤

您會在建立指標時建立使用者定義的標籤。計數器指標與分佈指標都可以有標籤。您無法在系統記錄式指標中加入標籤。

如要建立標籤，請在記錄項目中指定欄位，然後定義從指定欄位擷取值的運算式。

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

範例

本節提供幾個範例，協助您開始在使用者定義的記錄指標上建立標籤。建立標籤後，建議您使用 Metrics Explorer 驗證標籤。

提示：

• 指定擷取器運算式時，您必須使用擷取群組。
• 如果未指定擷取器運算式，系統會擷取欄位的完整值。

• 請確保任何標籤的可能值組合都受到限制。建議使用一小組離散值 (例如「紅色」、「綠色」和「藍色」)。舉例來說，如果您擷取顏色標籤的 8 位元 RGB 值，可以取得超過 1,600 萬個不同的值。也就是說，您最多可擁有 1,600 萬個時間序列。

  請勿擷取高解析度值，例如時間戳記、任何類型的專屬 ID、使用者 ID、IP 位址、未參數化的網址等等。

從稽核記錄中擷取狀態碼

如果欄位不含任何特殊字元，您可以使用欄位名稱做為記錄式指標的標籤。

舉例來說，稽核記錄的 protoPayload 欄位符合 AuditLog 結構。因此，如要從稽核記錄中擷取 status 欄位，您可以將欄位名稱設為 protoPayload.status.code，並將擷取器運算式留空。

如果您只想擷取錯誤代碼的第一個數字，可以將擷取器運算式設為 (\d)\d\d。

從含有特殊字元的欄位中擷取值

如果記錄項目中的欄位含有特殊字元，請以雙引號括住該欄位。

舉例來說，如要擷取 k8s-pod/k8s-app 標籤的完整值，請將欄位名稱設為 labels."k8s-pod/k8s-app"，並將運算式留空。

從文字酬載中擷取值

請考慮採用下列格式的記錄項目：

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

如要從使用先前格式的記錄項目中，擷取狀態值 (例如 deferred)，您可以採取以下做法：

• 欄位名稱：textPayload
• 擷取器運算式：^unfinished.*state: ([a-z]+)

從重複欄位擷取值

記錄項目可能包含含有重複欄位的欄位。在 JSON 中，這些欄位會以方括號 ([]) 顯示。從標籤的角度來看，請將重複欄位視為集合，並將標籤擷取器視為迭代器。定義標籤時，您會提供比對條件，而擷取器會重複處理集合，直到找到相符項目為止。系統一律會傳回第一個符合條件的項目，即使集合中有多個成員符合條件也是如此。

您決定建立記錄指標，用來計算稽核記錄。在設定標籤之前，您查看了幾個稽核記錄，並發現 protoPayload 的格式符合 AuditLog 結構。以下是稽核記錄項目的部分內容。

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

您決定為記錄指標建立標籤，以便儲存 permission 欄位的資訊。您會發現這些欄位的格式類似 io.k8s.xyz，其中 xyz 是提供要求詳細資料的字串。這個字串可能會包含 get 這類值，也可能會包含 io.k8s.coordination.v1.leases.get 這類較複雜的格式。

為了盡量減少標籤值的數量，請不要擷取詳細資訊。您只想在標籤中儲存 get 或 coordination 等值。此外，您決定不想在標籤值中加入常見的前置字串 io.k8s.。

接下來，您需要設定標籤。由於 permission 欄位是重複欄位，父項為 authorizationInfo 欄位，因此您可以將欄位名稱設為以下格式：

protoPayload.authorizationInfo.permission

最後，您可以建立下列規則運算式：

io.k8s.([a-z]+).*