時間序列的結構

本頁面將深入探討「指標、時間序列和資源」和「指標模型元件」一文中的討論和範例。如要充分運用這個頁面，請先閱讀上述頁面。

本頁面適用於想深入瞭解時間序列和 Cloud Monitoring 指標模型實作方式的讀者，特別是使用 Monitoring API 的讀者。包括自訂 (使用者定義) 指標的使用者。

本頁面會將一般指標模型對應至 Cloud Monitoring API，因此直接使用 Monitoring API 的使用者會覺得很有幫助。主要與 Google Cloud 控制台互動的使用者可能不需要這麼詳細的資訊。
如果您使用 OpenTelemetry 等第三方整合服務，這項功能也很有幫助。透過整合功能，外部來源的資料會傳送至 Cloud Monitoring，並對應至 Cloud Monitoring 指標模型，然後像其他指標資料一樣處理。

如要進一步瞭解如何收集自己的指標，請參閱使用者定義指標總覽。

指標模型審查

如要瞭解時間序列的結構，您必須先熟悉 Cloud Monitoring 使用的指標模型。這個模型請參閱「指標、時間序列和資源」。本節提供簡要回顧。

一般來說，監控資料會記錄在時間序列中。每個時間序列都包含三項與本討論相關的資訊：

一組附有時間戳記的資料點。
指標類型參照，可協助您解讀資料點。
資料來源受監控資源的參照。

Time series:

    Points: [(value₁, time₁), (value₂, time₂), ...]
    Metric type information: integer? incremental?
    Monitored resource: project? location? method?

每個時間序列都包含來自單一實體或邏輯來源的測量結果。如果環境中有數百個資源，每個資源至少會貢獻一個時間序列。事實上，如果指標類型和受監控資源類型有標籤，您會取得每個標籤值組合的時間序列；詳情請參閱「基數」。

時間序列範例

時間序列會以 TimeSeries 物件的例項表示。以下是單一時間序列的完整例項：

    {
      "metric": {
        "labels": {
          "log": "kubelet",
          "severity": "DEFAULT"
        },
        "type": "logging.googleapis.com/log_entry_count"
      },
      "resource": {
        "type": "gce_instance",
        "labels": {
          "instance_id": "5106847938295940291",
          "zone": "us-central1-a",
          "project_id": "a-gcp-project"
        }
      },
      "metricKind": "DELTA",
      "valueType": "INT64",
      "points": [
        {
          "interval": {
            "startTime": "2019-12-20T20:25:38Z",
            "endTime": "2019-12-20T20:26:38Z"
          },
          "value": {
            "int64Value": "20"
          }
        }
      ]
    }

大多數時間序列包含的資料點遠多於此處，這個時間序列涵蓋一分鐘間隔。所有時間序列的結構都相同，包含下列欄位：

「metric」欄位記錄
- 這個特定時間序列的指標標籤值，代表一組標籤值。
- 與資料相關聯的指標類型。指標類型會指定可用的標籤，並說明資料點代表的內容。
如要進一步瞭解這個欄位中的資訊，請參閱「指標」一文。
resource 欄位會記錄：
- 這個特定時間序列的資源標籤值，代表一組標籤值。
- 收集資料的特定受監控資源。
如要進一步瞭解這個欄位中的資訊，請參閱「受監控的資源物件」。
metricKind 和 valueType 欄位會說明如何解讀值。詳情請參閱「指標種類與類型」。
points 欄位是含有時間戳記值的陣列。指標類型會說明值代表的意義。範例時間序列的陣列只有一個資料點；在大多數時間序列中，陣列會有更多值。

如需擷取時間序列資料的即時範例，請參閱「時間序列：受控資源的資料」。

本頁接下來會更詳細地介紹 metric 和 resource 欄位中的資訊。

受控資源

Cloud Monitoring 會從受監控資源收集資料，並以時間序列記錄。建立的每個時間序列都會包含受監控資源的說明，資料就是從該資源收集而來。

受監控資源物件

受監控資源是以 MonitoredResource 物件的例項表示。受監控的資源會說明時間序列中的值來源。MonitoredResource 物件會嵌入時間序列，並識別 Monitoring 系統已知的受監控資源類型特定執行個體，指向實體或邏輯實體。

舉例來說，以下是描述特定 Compute Engine 執行個體的受監控資源物件，是從範例時間序列中擷取而來：

      "resource": {
        "type": "gce_instance",
        "labels": {
          "instance_id": "5106847938295940291",
          "zone": "us-central1-a",
          "project_id": "a-gcp-project"
        }
      }

這個受控資源執行個體的類型為 gce_instance，在專案 a-gcp-project 中具有特定 instance_id 值 (5106847938295940291)。執行個體位於美國。另一個時間序列可能來自這個受監控資源的不同執行個體。每個標籤值組合都會識別出收集資料的專屬資源。

不同資源適用不同的標籤組合。資源的標籤集是由該類型的受監控資源描述元決定。

受控資源描述元

受監控資源類型的相關資訊會保存在稱為「受監控資源描述元」的資料結構中。如要瞭解這個資料結構的定義，請參閱 MonitoredResourceDescriptor。

受監控資源描述元類似於記錄結構的結構定義或規格。不包含受監控資源特定執行個體的資料，而是說明如何描述特定類型的受監控資源。舉例來說，以下是 gce_instance 資源的受監控資源描述元：

{
  "type": "gce_instance",
  "displayName": "VM Instance",
  "description": "A virtual machine instance hosted in Compute Engine.",
  "name": "projects/[PROJECT_ID]/monitoredResourceDescriptors/gce_instance"
  "labels": [
    {
      "key": "project_id",
      "description": "The identifier of the GCP project associated with this resource, such as \"my-project\"."
    },
    {
      "key": "instance_id",
      "description": "The numeric VM instance identifier assigned by Compute Engine."
    },
    {
      "key": "zone",
      "description": "The Compute Engine zone in which the VM is running."
    }
  ],
}

將這個受控資源描述元與受控資源物件中顯示的特定gce_instance資源執行個體進行比較。這個描述元不會描述特定受監控資源，而是指定標籤，且每個標籤值組合都會識別特定受監控資源。

您可以使用 Cloud Monitoring API，在 Google Cloud 專案中擷取受監控資源描述元。舉例來說，請參閱 monitoredResourceDescriptors.list 和 monitoredResourceDescriptors.get 方法的參考頁面。

即時範例：如果您有 Google Cloud 專案，可以使用 APIs Explorer 小工具擷取這個描述元，如下所示：

開啟 monitoredResourceDescriptors.list 參考頁面。
在標示為「Try this method」的窗格中，輸入下列內容：
- 名稱：projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance
  
  將 PROJECT_ID 替換為 Google Cloud 專案 ID。
點選「Execute」。

要求會傳回上述描述元。

如需使用 Monitoring API 方法的範例，請參閱「列出指標和資源類型」。

指標

Cloud Monitoring 建立的每個時間序列都會記錄一組資料點，以及這些資料點的組織和意義相關資訊。

指標物件

每個時間序列都包含對指標物件中記錄資料說明的參照。

時間序列中包含的指標物件會指定評估類型，以及這些評估的指標專屬資訊。如要瞭解指標物件資料結構的定義，請參閱 Metric。舉例來說，以下是從「範例時間序列」中擷取的時間序列指標物件：

    {
      "metric": {
        "labels": {
          "log": "kubelet",
          "severity": "DEFAULT"
        },
        "type": "logging.googleapis.com/log_entry_count"
      }

這個物件會顯示時間序列包含 logging.googleapis.com/log_entry_count 個測量值。標籤值會告訴您，這個特定時間序列只會計算名為 kubelet 的記錄檔中，嚴重程度為 DEFAULT 的記錄項目。

每個標籤值組合都有一個時間序列，因此相同記錄檔的 INFO 項目會顯示在不同的時間序列中。

指標物件中收集的標籤組會在該指標類型的描述元中指定。

指標描述元

指標類型的相關資訊會儲存在稱為「指標描述元」的資料結構中。如要瞭解這個資料結構的定義，請參閱 MetricDescriptor。

指標描述元是記錄結構的結構定義或規格。這類資料不會包含特定指標的資料，而是說明如何解讀與特定指標類型相關聯的資料。

以下是指標描述元的範例：

{
  "type": "logging.googleapis.com/log_entry_count",
  "name": "projects/a-gcp-project/metricDescriptors/logging.googleapis.com/log_entry_count",
  "labels": [
    {
      "key": "log",
      "description": "Name of the log."
    },
    {
      "key": "severity",
      "description": "Severity of the log entry."
    }
  ],
  "metricKind": "DELTA",
  "valueType": "INT64",
  "unit": "1",
  "description": "Number of log entries that contributed to user-defined metrics.",
  "displayName": "Log entries",
  "metadata": {
    "launchStage": "GA",
    "samplePeriod": "60s"
  },
  "launchStage": "GA"
}

請將這個指標描述元與「指標物件」中顯示的指標物件進行比較。描述元會說明標籤值的意義，以及如何解讀資料點的值。

您可以使用 Cloud Monitoring API 擷取指標描述元。舉例來說，請參閱 metricDescriptors.list 和 metricDescriptors.get 方法的參考頁面。