建立分佈指標

本頁面說明如何使用 GCP 主控台與 Stackdriver Logging API 建立分佈類型記錄指標

總覽

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

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

建立分佈指標

Logging 主控台

請按照下列步驟在 GCP 主控台中建立記錄指標:

  1. 在 GCP 主控台的左側導覽清單中按一下 [Stackdriver Logging] > [Logs-based Metrics] (記錄指標),或按一下下列按鈕:

    前往記錄檢視器

  2. 使用頁面頂端的下拉式選單選取專案。

  3. 按一下頁面頂端的 [Create Metric] (建立指標)。您會在頁面右側看見「Metric Editor」(指標編輯工具),檢視器面板會在左側顯示您的記錄:

    建立分佈指標

  4. 在檢視器面板中建立篩選器,僅顯示您要在指標中計數的記錄項目。

    基本篩選器可在記錄項目上方的下拉式選單中找到。您也可以按一下搜尋列右側的下拉式選單,並選取 [轉換為進階篩選器],來存取進階篩選器介面。

    詳情請參閱使用者介面一文。

  5. 在「Metric Editor」(指標編輯工具) 面板中,設定下列欄位:

    • 名稱:選擇在專案的記錄指標中不重複的名稱。存在一些命名限制;詳情請參閱疑難排解一文。
    • 說明:說明指標。
    • 標籤:(選填) 為每個標籤按一下 [Add Item] (新增項目) 來新增標籤。如要進一步瞭解如何定義標籤,請參閱記錄指標標籤一文。
    • 單位:(選填) 對於分佈指標,您可以選擇性地輸入單位,例如 sms 等。詳情請參閱 MetricDescriptorunit 欄位。
    • 類型:「Distribution」(分佈)
    • 欄位名稱:輸入包含分佈值的記錄項目欄位。您會在輸入時看到一些選擇。例如:

      jsonPayload.latency
      
    • 擷取運算式:(選填) 如果「Field name」(欄位名稱) 一律包含可轉換為 double 類型的數值,您就可以將這個欄位保留空白。否則,請指定從欄位值擷取數字分佈值的規則運算式。「Build」(建構) 選單可用來以互動方式建構及驗證規則運算式。

      範例。假設您的 latency 記錄項目欄位包含一個數字,後跟 ms (表示毫秒)。以下規則運算式會選擇不含單位後置字串的數字:

      ([0-9.]+)ms
      

      圓括號,又稱為 regexp 擷取群組,可識別將擷取之文字比對的部分。如要進一步瞭解規則運算式,請參閱 RE2 語法一文。

    • 更多 (直方圖值區):(選填) 按一下 [More] (更多) 可開啟一個表單部分,您可以使用此表單部分指定自訂值區版面配置。如果您沒有指定值區版面配置,系統會提供預設值區版面配置。詳情請參閱本頁面的直方圖值區一文。

  6. 按一下 [Create Metric] (建立指標)

Logging API

如要建立分佈指標,請使用 Stackdriver Logging API 的 projects.metrics.create 方法。您可以試用 [APIs Explorer][apis-explorer-create] 中的方法。如下準備方法的引數:

  1. parent 欄位設定為要建立指標的所在專案:

    projects/[PROJECT_ID]
    
  2. 將要求主體設定為 LogMetric 物件。分佈指標物件範例如下:

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_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 物件。metricKind 必須是 DELTAvalueType 必須是 DISTRIBUTION

直方圖值區

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

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

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

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

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

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

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

    上限:範圍[i],(0 <= i < N-1)
    下限:範圍[i - 1],(1 <= i < N)

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

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

Logging 主控台

當您建立分佈指標並按一下 [指標編輯工具] 表單中的 [更多] 時,會開啟「直方圖值區」子選單。 以下顯示「線性」值區版面配置的這個子選單:

直方圖值區

線性 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]

如需進一步瞭解值區,請參閱 Stackdriver Monitoring API 中的 BucketOptions 一文。

Logging 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]

明確 Bucket:邊界會個別列出。

{ # 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 ^ ii=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]

新指標延遲時間

您的新指標會立即出現在記錄檢視器的指標清單與相關 Stackdriver Monitoring 選單中。但是,指標可能需要一分鐘的時間才能開始收集比對記錄項目的資料。

檢查分佈指標

如要列出 GCP 專案中的記錄指標,或檢查專案中的特定指標,請執行下列操作:

Logging 主控台

按一下下列按鈕,前往「記錄指標」頁面,此頁面會列出目前專案中的所有記錄指標:

前往「Logs-based Metrics」(記錄指標)

如要查看記錄指標中的資料,請從指標清單右側的溢位選單中選取 [在 Metrics Explorer 中查看]

Logging API

列出指標

如要列出專案中的使用者定義的記錄指標,請使用 projects.metrics.list API 方法。 如下填入方法的參數:

  • parent:專案的資源名稱:projects/[PROJECT_ID]
  • pageSize:結果數上限。
  • pageToken:取得下一個頁面的結果。請參閱 projects.metrics.list 一文。

擷取指標定義

如要擷取單一使用者定義的記錄指標,請使用 projects.metrics.get API 方法。 如下填入方法的參數:

  • metricName:指標的資源名稱:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

讀取指標資料

如要讀取記錄指標中的時間序列資料,請使用 Stackdriver Monitoring API 中的 projects.timeseries.list。詳情請參閱讀取時間序列的說明。 以下是您在記錄指標方面所需的資訊:

  • 指標類型為 logging.googleapis.com/user/[METRIC_ID]

Cloud SDK

如要列出專案中的使用者定義的記錄指標,請使用下列指令:

gcloud logging metrics list

如要顯示專案中的使用者定義的記錄指標,請使用下列指令:

gcloud logging metrics describe [METRIC_NAME]

如需詳細資料,請使用下列指令:

gcloud logging metrics --help

您無法從 Cloud SDK 讀取指標的時間序列資料。

更新分佈指標

您可以更新記錄指標,以變更在指標中參照的欄位說明、篩選器與名稱。您可將新標籤新增至指標,並可變更用來擷取指標值及其標籤值的規則運算式。

您無法變更記錄指標或其標籤的名稱或類型,也無法刪除記錄指標中的現有標籤。

如要編輯或更新記錄指標,請按照以下步驟操作:

Logging 主控台

  1. 前往「記錄指標」頁面:

    前往「Logs-based Metrics」(記錄指標)

  2. 按一下您要編輯的記錄指標右側選單中的 [Edit metric] (編輯指標)

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

  4. 按一下 [Done] (完成)

Logging API

如要編輯或更新記錄指標,請使用 API 中的 projects.metrics.update 方法。如下設定欄位:

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

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    例如:

    projects/my-gcp-project/metrics/my-error-metric
    
  • 在要求主體中,包含與現有指標完全相同的 LogMetric 物件,但您要變更及新增的指標除外。

Cloud SDK

您只能使用 Cloud SDK 變更現有指標的說明與篩選器。

如要更新記錄指標,請使用下列指令。您可以指定以下一個或兩個標記:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

如需詳細資料,請使用下列指令:

gcloud logging metrics update --help

刪除分佈指標

如要刪除記錄指標,請按照以下步驟操作:

Logging 主控台

  1. 前往「記錄指標」頁面:

    前往「Logs-based Metrics」(記錄指標)

  2. 選取您要刪除的指標,並按一下頁面頂端的 [Delete] (刪除)

    您也可以按一下您要刪除的記錄指標右側選單中的 [Delete metric] (刪除指標)

Logging API

使用 API 中的 projects.metrics.delete 方法。

Cloud SDK

使用下列指令刪除目前專案中的使用者定義的記錄指標:

gcloud logging metrics delete [METRIC_NAME]

如需詳細資料,請使用下列指令:

gcloud logging metrics delete --help

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁