時系列の構造

このページでは、指標、時系列、リソースおよび指標モデルのコンポーネントで取り上げるディスカッションと例について詳しく説明します。このページを最大限に活用するには、まず最初にこれらのページをご覧ください。

このページは、時系列と Cloud Monitoring 指標モデルの実装について詳しく知りたい方、特に Monitoring API を使用している方を対象としています。これには、カスタムの（ユーザー定義）指標のユーザーが含まれます。

このページでは、一般的な指標モデルを Cloud Monitoring API にマッピングしているので、Monitoring API を直接使用しているユーザーに役立ちます。Google Cloud コンソールをメインに操作するユーザーは、ここまで詳しい内容に関する知識は必要ありません。
また、OpenTelemetry などのサードパーティの統合を使用するすべてのユーザーにも便利です。外部ソースから取得したデータは、統合された Cloud Monitoring に到達し、Cloud Monitoring 指標モデルにマッピングされ、他の指標データと同様に処理されます。

独自の指標の収集について詳しくは、ユーザー定義指標の概要をご覧ください。

指標モデルの確認

時系列の構造を理解するための前提条件として、Cloud Monitoring で使用される指標モデルに関する知識が必要です。このモデルは、指標、時系列、リソースで説明されています。このセクションでは、簡単に復習します。

一般に、モニタリングデータは時系列で記録されます。個々の時系列には、この検討に関連する 3 つの情報が含まれます。

タイムスタンプが付いたデータポイントのセット。
データポイントの解釈方法を示す指標タイプへの参照。
データの発生元からモニタリング対象リソースへの参照。

各時系列は、単一の物理ソースまたは論理ソースからの測定値を保持します。環境に数百個のリソースがある場合、各リソースは少なくとも 1 つの時系列に貢献します。実際、指標タイプとモニタリング対象リソースタイプにラベルがある場合、ラベル値の組み合わせごとに 1 つの時系列が生成されます。詳細については、カーディナリティをご覧ください。

サンプル時系列

時系列は、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"
          }
        }
      ]
    }

ほとんどの時系列にはもっと多くのデータポイントが含まれます。このサンプル時系列がカバーしているのは、1 分間隔です。すべての時系列は同じ構造で、次のフィールドがあります。

metric フィールドには次の情報が記録されます。
- この特定の時系列の指標ラベル値。ラベル値の 1 つの組み合わせを表します。
- データが関連付けられている指標タイプ。使用可能なラベルを指定し、データポイントで表される内容を説明する指標タイプ
このフィールドの情報の詳細については、指標をご覧ください。
resource フィールドには次の情報が記録されます。
- この特定の時系列のリソースラベル値。ラベル値の 1 つの組み合わせを表します。
- データが収集された特定のモニタリング対象リソース
このフィールドの情報の詳細については、モニタリング対象リソースオブジェクトをご覧ください。
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）があります。インスタンスは米国にあります。別の時系列は、このモニタリング対象リソースの別のインスタンスから取得された可能性があります。ラベル値の組み合わせごとに、データの収集元の独自のリソースを識別します。

それぞれ異なるラベルのセットは、さまざまなリソースに適しています。リソースのラベルのセットは、そのタイプのモニタリング対象リソース記述子によって決まります。

monitoredResourceDescriptors

モニタリング対象リソースタイプに関する情報は、モニタリング対象リソース記述子と呼ばれるデータ構造に保持されます。このデータ構造の定義については、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 プロジェクトがある場合は、次のように API Explorer ウィジェットを使用してこの記述子を取得できます。

monitoredResourceDescriptors.list リファレンスページを開きます。
[Try this method] というラベルが付いたペインに、次のコードを入力します。
- 名前: projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance
  
  PROJECT_ID は、Google Cloud プロジェクトの ID に置き換えます。
[実行] をクリックします。

リクエストは、前の記述子を返します。

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 のログエントリのみをカウントすることを示しています。

ラベル値の組み合わせごとに 1 つの時系列があるため、同じログファイルへの 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 メソッドのリファレンスページをご覧ください。