設定分布指標

本頁面說明如何使用Google Cloud 控制台、Logging API 和 Google Cloud CLI 建立分布類型的記錄指標。如要查看記錄指標的整體情況，請參閱「記錄指標總覽」。

總覽

分佈指標需要篩選器來選取相關記錄項目，也需要值擷取器來抓取分佈的數值。值擷取器的種類與用於使用者定義標籤的種類相同。

分佈指標會在直方圖值區中記錄擷取值的統計分佈。擷取的值不會單獨記錄，但會記錄其跨設定值區的分佈，以及值的計數、平均值與離均差平方和。您可在分佈中使用直方圖值區的預設版面配置，也可以微調值區的邊界以概略擷取值。

如要進一步瞭解如何查看及解讀分佈指標，請參閱「分佈指標」一文。

事前準備

1. 如要使用記錄指標，您必須擁有啟用帳單的 Google Cloud 專案：

   Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   1. 確認您的 Identity and Access Management 角色包含建立及查看記錄型指標，以及建立快訊政策所需的權限。詳情請參閱「記錄指標的權限」。

   建立分布指標

   這項指標會計算符合您提供篩選條件的記錄項目。您可以在篩選器中使用規則運算式，建議您加入資源類型。篩選條件長度不得超過 20,000 個字元。

   請勿在篩選器中輸入私密資訊。篩選器會視為服務資料。

   注意： 如要根據稽核記錄建立記錄指標，請參閱下方的「疑難排解」一節。

   控制台

   請按照下列步驟，在專案的Google Cloud 控制台中建立記錄計數器指標： Google Cloud

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

      前往「記錄指標」

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

   2. 點選「建立指標」之後，系統會顯示「建立記錄指標」面板。

   3. 設定「指標類型」：選取「分布」。

   4. 在「詳細資料」部分中，設定下列欄位：

      • 記錄指標名稱：選擇在 Google Cloud 專案的記錄指標中不重複的名稱。存在一些命名限制；詳情請參閱疑難排解一文。
      • 說明：輸入指標說明。
      • 單位：(選填) 對於分佈指標，您可以選擇性地輸入單位，例如 s 和 ms。詳情請參閱 MetricDescriptor 的 unit 欄位。

   5. 在「篩選器選取」部分定義指標篩選器。

      1. 使用「選取專案或記錄檔 bucket」選單，選取指標的計數範圍。可以選擇專案中的記錄項目，或是僅限特定記錄檔 bucket 中的記錄項目。 Google Cloud

      2. 使用記錄查詢語言建立篩選器，只收集您要在指標中計數的記錄項目。您也可以使用規則運算式建立指標的篩選器。

      3. 欄位名稱：輸入包含分佈值的記錄項目欄位。您會在輸入時看到一些選擇。例如：

         protoPayload.latency
         

      4. 規則運算式：(選填) 如果「Field name」(欄位名稱) 一律包含可轉換為 double 類型的數值，您就可以將這個欄位保留空白。否則，請指定從欄位值擷取數字分佈值的規則運算式。

         範例。假設您的 latency 記錄檔項目欄位包含一個數字，後面接著以毫秒為單位的 ms。以下規則運算式會選擇不含單位後置字串的數字：

         ([0-9.]+)
         

         圓括號，又稱為 regexp 擷取群組，可識別將擷取之文字比對的部分。詳情請參閱使用規則運算式。

      • 進階 (直方圖值區)：(選填) 按一下「進階」可開啟表單部分，您可以使用此表單部分指定自訂值區版面配置。如果您沒有指定 bucket 版面配置，系統會提供預設 bucket 版面配置。詳情請參閱本頁面的「直方圖值區」一文。
      1. 如要查看符合篩選條件的記錄項目，請按一下「預覽記錄」。

   6. (選用) 在「標籤」部分新增標籤。如需建立標籤的操作說明，請參閱「建立標籤」。

   7. 按一下「建立指標」即可建立指標。

   gcloud

   如要建立分配類型記錄檔的指標，請建立包含 LogMetric 定義表示法的檔案 (JSON 或 YAML 格式)。然後使用下列指令，從檔案讀取設定：

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

   如要瞭解如何說明分布的直方圖值區，請參閱「直方圖值區」。

   API

   如要建立分配指標，請使用 Logging API 的 projects.metrics.create 方法。如果您使用參考資料頁面上的 APIs Explorer 窗格，請準備引數，如下所示：

   1. 將 parent 欄位設定為要建立指標的專案或值區：

      • 如果是專案範圍的記錄指標，請指定專案：

      projects/PROJECT_ID
      

      • 如果是 bucket 範圍的記錄指標，請指定 bucket：

      projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
      

   2. 將要求主體設定為 LogMetric 物件。分佈指標的物件範例如下。

      {
        name:        "my-metric"
        description: "Description of my-metric."
        filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
        valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",
      
        labelExtractors: {
          "my-label-1":
            "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
          "my-label-2":
            "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
        },
        bucketOptions: { [SEE_BELOW] },
      
        metricDescriptor: {
            metricKind: DELTA,
            valueType: DISTRIBUTION,
            unit: "ms",
      
            labels: [
              {
                key: "my-label-1",
                valueType: STRING,
                description: "Description of string my-label-1.",
              },
              {
                key: "my-label-2",
                valueType: INT64,
                description: "Description of integer my-label-2.",
              }
            ]
        },
      }
      

   注意：

   • 存在一些命名限制；詳情請參閱疑難排解一文。

   • metricDescriptor：MetricDescriptor 物件。metricKind 必須為 DELTA。valueType 必須為 DISTRIBUTION。

   直方圖值區

   分佈指標包含一個直方圖，可計算位於指定範圍 (值區) 之內的值數目。分佈指標中最多可以有 200 個值區。

   每個值區都有兩個邊界值：「L」與「H」，這兩個邊界值定義了值區包含的最低與最高值。值區的寬度是「H」-「L」。 由於值區之間不能有缺口，一個值區的下邊界會與之前值區的上邊界相同，依此類推。因此邊界不會位於一個以上的值區中，值區會包含值區的下邊界；值區的上邊界屬於下一個值區。

   所有值區版面配置都可以藉由以遞增順序列出個別值區之間的邊界值來指定。第一個值區是欠位值區，這個值區會計算小於第一個邊界的值。最後一個值區是溢位值區，會計算大於或等於最後一個界限的值。其他值區會計算大於或等於其下邊界及小於其上邊界的值。如有 n 個邊界值，則有 n+1 個值區。排除欠位與溢位值區，會有「n-1」n-1個有限值區。

   有三種不同的方法可以指定分佈指標的直方圖值區之間的邊界。您可為邊界值指定公式，也可列出邊界值：

   • 線性(offset、width、i)：每個值區的寬度都相同。 邊界為 offset + width * i，i=0,1,2,...,N。如要進一步瞭解線性值區，請參閱 API 參考資料。

   • 指數(scale、growth_factor、i)：較高值的值區寬度會增加。邊界為 scale * growth_factorⁱ，i=0,1,2,...,N。如要進一步瞭解指數值區，請參閱 API 參考資料。

   • 明確：以「範圍」陣列列出值區的所有邊界。值區 i 有下列邊界：

     Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
     Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)
     

     如要進一步瞭解明確值區，請參閱 API 參考資料。

   我們會在下一節中說明您指定直方圖值區的方式：

   控制台

   建立分配指標並在「指標編輯工具」表單中點選「更多」時，系統會開啟「直方圖值區」子選單。 以下子表單適用於「線性」值區版面配置：

   

   線性 Bucket：如下填入直方圖值區表單。

   • 類型：「Linear」(線性)
   • 起始值 (a)：第一個有限值區的下邊界。 這個值在 API 中稱為「偏移」。
   • 值區數 (N)：有限值區數。這個值必須大於或等於 0。
   • 特徵分塊寬度 (b)：每個有限值區中，上限與下限的差。這個值必須大於 0。

   例如，如果起始值是 5，值區數是 4，且值區寬度是 15，則值區範圍如下所示：

   (-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)
   

   明確 Bucket：如下填入直方圖值區表單：

   • 類型：「Explicit」(明確)
   • 界限 (b)：以半形逗號分隔的有限值區邊界值清單。這也決定了值區數及其寬度。

   例如，如果邊界清單是：

   0, 1, 2, 5, 10, 20
   

   則會有五個範圍如下的有限值區：

   (-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)
   

   指數 Bucket：如下填入直方圖值區表單：

   • 類型：「Exponential」(指數)

   • 值區數 (N)：有限值區的總數。 這個值必須大於 0。

   • 線性比例 (a)：值區的線性比例。這個值必須大於 0。

   • 指數成長因子 (b)：值區的指數成長因子。這個值必須大於 1。

   舉例來說，如果 N=4、a=3 且 b=2，則區間範圍如下：

   (-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)
   

   如要進一步瞭解值區，請參閱 Cloud Monitoring API 中的 BucketOptions。

   API

   選用值區版面配置由 LogMetric 物件中的 bucketOptions 欄位指定，該物件會提供給 projects.metrics.create。如需瞭解完整 LogMetric 物件，請參閱本頁面的「建立分佈指標」一節。值區版面配置的增補內容如下所示：

   線性 Bucket：

   { # LogMetric object
     ...
     bucketOptions: {
       linearBuckets: {
         numFiniteBuckets: 4,
         width: 15,
         offset: 5
       }
     },
     ...
   }
   

   上方的範例建立了下列值區：

   (-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)
   

   明確值區：個別列出邊界。

   { # LogMetric object
     ...
     bucketOptions: {
       explicitBuckets: {
         bounds: [0, 1, 2, 5, 10, 20 ]
       }
     },
     ...
   }
   

   上方的範例建立了下列值區：

   (-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)
   

   指數值區：邊界為 scale * growthFactor ^ i，i=0,1,2, ..., numFiniteBuckets

   { # LogMetric object
     ...
     bucketOptions: {
       exponentialBuckets: {
         numFiniteBuckets: 4,
         growthFactor: 2,
         scale: 3
       }
     },
     ...
   }
   

   上方的範例建立了下列值區：

   (-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)
   

   新指標延遲時間

   新指標會立即顯示在指標清單和相關的 Monitoring 選單中。不過，指標最多可能需要一分鐘，才會開始收集相符記錄項目的資料。

   檢查分布指標

   如要列出 Google Cloud 專案中的使用者定義記錄指標，或檢查 Google Cloud 專案中的特定指標，請按照下列步驟操作：

   控制台

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

      前往「記錄指標」

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

   2. 在「使用者定義的指標」窗格中，您會看到目前 Google Cloud 專案中的使用者定義記錄指標：

   3. 如要查看記錄指標中的資料，請按一下指標列中的「選單」，然後選取「在 Metrics Explorer 中查看」。

   gcloud

   如要列出 Google Cloud 專案中使用者定義的記錄指標，請使用下列指令：

   gcloud logging metrics list
   

   如要在 Google Cloud 專案中顯示使用者定義的記錄指標，請使用下列指令：

   gcloud logging metrics describe METRIC_NAME
   

   如要取得說明，請使用下列指令：

   gcloud logging metrics --help
   

   您無法透過 Google Cloud CLI 讀取指標的時間序列資料。

   API

   列出指標

   如要列出 Google Cloud 專案中使用者定義的記錄指標，請使用 projects.metrics.list API 方法。按照下列方式填寫方法參數：

   • parent： Google Cloud 專案的資源名稱： projects/PROJECT_ID。
   • pageSize：結果數上限。
   • pageToken：取得下一個頁面的結果。如要瞭解如何使用網頁權杖，請參閱 projects.metrics.list。

   擷取指標定義

   如要擷取單一使用者定義的記錄指標，請使用 projects.metrics.get API 方法。按照下列方式填寫方法參數：

   • metricName：指標的資源名稱：

     projects/PROJECT_ID/metrics/METRIC_ID
     

   讀取指標資料

   如要讀取記錄指標中的時間序列資料，請使用 Cloud Monitoring API 中的 projects.timeseries.list。如要瞭解時間序列資料，請參閱「讀取時間序列」。

   如要讀取單一使用者定義的記錄指標，請填入這個指標類型和 ID，做為方法參數：

   logging.googleapis.com/user/METRIC_ID
   

   更新分布指標

   您可以編輯使用者定義的記錄指標，變更說明、篩選器，以及指標中參照的欄位名稱。您可以為指標新增標籤，也可以變更用於擷取指標及其標籤值的規則運算式。如果您使用的是以 bucket 為範圍的指標，也可以更新指標的 bucket。

   您無法變更使用者定義的記錄指標名稱、類型或標籤，也無法刪除記錄指標中的現有標籤。

   如要編輯記錄指標，請按照下列步驟操作：

   控制台

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

      前往「記錄指標」

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

   2. 在要修改的記錄指標的「選單」中，按一下「編輯指標」。

   3. 變更指標中的允許項目。

   4. 按一下「更新指標」。

   gcloud

   使用 Google Cloud CLI 變更計數器指標的說明、篩選器查詢和 bucket。你可以一次更新所有欄位，也可以只更新部分欄位。

   gcloud logging update METRIC_NAME \
     --description="METRIC_DESCRIPTION" \
     --log-filter="FILTER" \
     --bucket-name=BUCKET_NAME
   

   如果變更與值區範圍指標相關聯的值區，則變更前收集的任何指標資料，都不會再反映目前的設定。系統不會移除先前儲存區收集的指標資料。

   注意： METRIC_NAME 值必須與 Google Cloud 專案中現有的記錄檔指標相符，否則更新指令會建立新的指標。

   如要更新分配指標或其他計數器指標欄位 (不含 METRIC_NAME)，請建立檔案，其中包含 JSON 或 YAML 格式的修訂版 LogMetric 規格。接著，使用 --config-from-file 欄位呼叫 update 指令，更新指標，並將 FILENAME 替換為 JSON 或 YAML 檔案的名稱：

   gcloud logging update METRIC_NAME --config-from-file FILENAME
   

   如需詳細資料，請使用下列指令：

   gcloud logging metrics update --help
   

   API

   如要編輯記錄指標，請使用 API 中的 projects.metrics.update 方法。將欄位設定如下：

   • metricName：指標的完整資源名稱：

     projects/PROJECT_ID/metrics/METRIC_ID
     

     例如：

     projects/my-gcp-project/metrics/my-error-metric
     

   • 在要求主體中，包含與現有指標完全相同的 LogMetric 物件，但您要變更及新增的指標除外。

   刪除分布指標

   如要刪除使用者定義的記錄指標，請按照下列步驟操作：

   控制台

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

      前往「記錄指標」

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

   2. 選取要刪除的指標，然後按一下「刪除」。

      您也可以按一下要刪除的記錄指標 選單 中的「刪除指標」。

   gcloud

   使用下列指令，在目前的 Google Cloud 專案中刪除使用者定義的記錄型指標：

   gcloud logging metrics delete METRIC_NAME
   

   如需詳細資料，請使用下列指令：

   gcloud logging metrics delete --help
   

   API

   如要刪除使用者定義的記錄指標，請使用 API 中的 projects.metrics.delete 方法。

   此外，在 Google Cloud 控制台的「記錄指標」頁面中，記錄指標介面的「使用者定義的指標」窗格提供更多功能，可協助您管理Google Cloud 專案中的使用者定義指標。詳情請參閱使用者定義指標。