設定記錄指標的標籤

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

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

記錄指標標籤總覽

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

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

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

您可以從 LogEntry 內建欄位 (例如 httpRequest.status) 或酬載欄位 textPayload、jsonPayload 或 protoPayload 中擷取標籤。不過，您無法從 errorGroups 欄位擷取錯誤群組的 ID。

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

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

注意： 請僅在您需要識別值以分類或摘述指標資料時才建立標籤。請勿使用標籤為資料欄位命名。

使用者定義標籤的限制

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

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

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

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

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

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

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

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

注意： 請勿擷取每個記錄項目專屬的標籤值，例如完整的 insertId 或 timestamp 欄位。您擁有的時間序列數會等於記錄項目數，且每一個時間序列都會包含一個資料點。

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

預設標籤

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

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

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

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

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

使用 Metrics Explorer 查看標籤

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

1. 在 Google Cloud 控制台中，前往「記錄指標」頁面：

   前往「記錄指標」

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

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

   如果已建立以記錄為準的指標，請先等待圖表顯示資料，再繼續操作 (可能需要幾分鐘)。

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

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

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

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

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

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

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

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

建立標籤

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

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

控制台

1. 建立記錄指標時，「建立記錄指標」面板會顯示新增標籤的選項。

2. 按一下「新增標籤」。

   提示：如要查看記錄項目內的欄位與值，請執行下列操作：

   1. 在「篩選器選取」部分，按一下「預覽記錄」。
   2. 在「View logs」(查看記錄) 窗格中，選擇記錄項目，然後按一下旁邊的展開器 。
   3. 按一下「Expand nested fields」(展開巢狀欄位)。

3. 在「標籤」部分中設定下列欄位：

   1. 標籤名稱：輸入標籤名稱，例如，ID。
      

      名稱必須符合下列條件：

      • 長度不可超過 100 個字元。
      • 符合規則運算式 [a-zA-Z][a-zA-Z0-9_]*。
      • 不只包含「log」字串。

   2. 說明：說明標籤。關於預期記錄值的格式，請試著儘可能具體說明，例如：Instance number。

   3. 標籤類型：選擇 [String] (字串)、[Boolean] (布林值) 或 [Integer] (整數)。

   4. 欄位名稱：輸入包含標籤值的記錄項目欄位名稱。您會在輸入時看到一些選擇。在此範例中，欄位為：

      labels."compute.googleapis.com/resource_id"
      

   5. 規則運算式：如果標籤值包含欄位的完整內容，您可以將此欄位保留空白。否則，請指定從欄位值中擷取標籤值的 regexp 擷取群組。

      舉例來說，假設欄位通常包含類似以下這樣的文字：

      The instance number is 0123456789; the ID is my-test-instance22
      

      如果您希望標籤值是執行個體數，有許多規則運算式可以擷取正確的數目。 舉例來說，在下列運算式中，圓括號是擷取群組，可識別要擷取的文字部分：

      The instance number is ([0-9]+); .*
      

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

4. 按一下 [Done] (完成) 建立標籤。您可以重複以上步驟新增更多標籤。

5. 如要完成指標建立程序，請按一下「建立指標」。

gcloud

如要建立含有自訂標籤的記錄檔指標，您必須建立檔案，其中包含 JSON 或 YAML 格式的 LogMetric 定義表示法，包括自訂標籤。接著，使用 --config-from-file 旗標呼叫 create 指令，建立指標。請將 FILENAME 替換為 JSON 或 YAML 檔案的名稱：

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

詳情請參閱 gcloud logging metrics create。

API

呼叫 Logging API 的 projects.metrics.create 方法時，標籤會列在呼叫要求主體的 LogMetric 物件中。如要進一步瞭解完整的呼叫方法，請參閱建立計數器指標一文或建立分佈指標一文。

您必須在 LogMetric 中，為每個標籤的 metricDescriptor 及 labelExtractors 欄位加上區隔。

語法如下：

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

語法元素的意義如下：

• LABEL_NAME：標籤做為字串的名稱。
• VALUE_TYPE：標籤類型，即 STRING、BOOL 或 INT64。
• LABEL_DESCRIPTION：標籤的說明。

• EXTRACTOR_EXPRESSION：將記錄項目欄位名稱與選用規則運算式組合在一起的字串，擷取器運算式可以是下列其中一項：

  EXTRACT(FIELD)
  

  REGEXP_EXTRACT(FIELD, REGEXP)
  

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

兩個標籤的範例如下：

{
  ...
  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)",
  },
}

詳情請參閱 LogMetric 類型。

範例

本節提供幾個範例，協助您開始為使用者定義的記錄指標建立標籤。建立標籤後，建議您使用 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]+).*