ユーザー定義の指標の概要

ユーザー定義指標はすべて、Google Cloud によって定義されていない指標です。これらには、ユーザーが定義できる指標と、サードパーティ アプリケーションによって定義される指標が含まれます。ユーザー定義指標を使用すると、アプリケーション固有のデータやクライアント側のシステムデータを取得できます。 Cloud Monitoring によって収集された組み込み指標では、バックエンドのレイテンシやディスク使用量に関する情報は得ることができますが、アプリケーションが生成したバックグラウンド ルーチンの数などは確認できません。

指標は、ログエントリの内容に基づくものを作成することもできます。ログベースの指標はユーザー定義指標のクラスですが、Cloud Logging から作成する必要があります。ログベースの指標について詳しくは、ログベースの指標の概要をご覧ください。

ユーザー定義指標は、カスタム指標またはアプリケーション特有の指標と呼ばれることもあります。これらの指標を使用すると、Cloud Monitoring の組み込み指標では定義できない情報を定義して、サードパーティ アプリケーションで収集できます。 ユーザーはこれらの指標を、コードを設定するためにライブラリによって提供されている API を使用して取得し、Cloud Monitoring などのバックエンド アプリケーションに送信します。

ログベースの指標以外のユーザー定義指標は、Cloud Monitoring API を直接使用して作成できます。ただし、OpenTelemetry を使用することをおすすめします。ユーザー定義指標を作成する方法については、次のドキュメントをご覧ください。

  • OTLP 指標とトレースを収集するでは、Ops エージェントとエージェントの OpenTelemetry Protocol（OTLP）レシーバーを使用して、OpenTelemetry を使用してインストゥルメント化され、Compute Engine で実行されているアプリケーションから指標とトレースを収集する方法について説明します。

  • Google Cloud Managed Service for Prometheus では、Google Kubernetes Engine と Kubernetes で実行されているアプリケーションから Prometheus 指標を収集する方法について説明しています。

  • Prometheus の指標収集するでは、Ops エージェントを使用して、Compute Engine で実行されているアプリケーションから Prometheus の指標を収集する方法について説明します。

  • API を使用してユーザー定義指標を作成するでは、Cloud Monitoring API を使用して指標を作成する方法と、その指標に指標データを追加する方法が説明されています。 このドキュメントでは、API Explorer、C#、Go、Java、Node.js、PHP、Python、Ruby の各プログラミング言語を使用し、Monitoring API を使用する方法が例を使って説明されています。

  • Cloud Run でカスタム指標を作成するでは、Cloud Run デプロイで OpenTelemetry Collector をサイドカー エージェントとして使用する方法について説明します。

Cloud Monitoring に関する限り、組み込み指標などのユーザー定義指標を使用できます。これらの指標は、グラフ化、アラートの設定、読み取りが可能です。指標データの読み取りについては、次のドキュメントをご覧ください。

  • 指標とリソースタイプを一覧表示するでは、ユーザー定義と組み込みの指標タイプを一覧表示して調べる方法が説明されています。たとえば、そのドキュメント内の情報を使用して、プロジェクト内のすべてのユーザー定義の指標記述子を一覧表示できます。
  • 時系列データの取得では、Monitoring API を使用して指標から時系列データを取得する方法について説明します。たとえば、このドキュメントでは、API を使用して Google Cloud プロジェクトの仮想マシン（VM）インスタンスの CPU 使用率を取得する方法が説明されています。

Google Cloud コンソールには、ユーザー定義指標の使用状況を表示する専用のページがあります。このページの内容については、指標の使用状況の表示と管理をご覧ください。

ユーザー定義指標の指標記述子

各指標タイプには、指標データの編成方法を定義する指標記述子が必要です。指標記述子は、指標と指標の名前のラベルも定義します。たとえば、指標リストには、すべての組み込み指標タイプの指標記述子が表示されます。

Cloud Monitoring では、書き込んだ指標データを使用して指標記述子を作成することも、指標記述子を明示的に作成してから指標データを書き込むこともできます。いずれの場合も、指標データの編成方法を決定する必要があります。

設計例

単一のマシンで実行されているプログラムがあり、このプログラムが補助プログラム A と B を呼び出すとします。ここで、プログラム A と B が何回呼び出されるかカウントする必要があるとします。また、プログラム A が 1 分あたり 10 回以上呼び出された時刻と、プログラム B が 1 分あたり 5 回以上呼び出された時刻も知りたいとします。最後に、Google Cloud プロジェクトは 1 つで、global モニタリング対象リソースにデータを書き込むものとします。

この例では、ユーザー定義指標に使用できるいくつかの設計について説明します。

  • 2 つの指標を使用する: Metric-type-A はプログラム A への呼び出しをカウントし、Metric-type-B はプログラム B への呼び出しをカウントします。この場合、Metric-type-A と Metric-type-B にはそれぞれ 1 つの時系列が含まれます。

    2 つの条件を含むアラート ポリシーを 1 つ作成することも、このデータモードを使用して 1 つの条件で 2 つのアラート ポリシーを作成することもできます。アラート ポリシーは複数の条件をサポートできますが、通知チャネルの構成は 1 つです。

    このモデルは、モニタリング対象のアクティビティ間のデータの類似性に関心がない場合に適しています。この例では、アクティビティとはプログラム A と B の呼び出し率です。

  • 1 つの指標を使用し、ラベルを使用してプログラム ID を保存します。 たとえば、そのラベルでは A や B の値を保存できます。Monitoring は、ラベルの一意の組み合わせごとに時系列を作成します。そのため、ラベル値が A の時系列と、ラベル値が B の別の時系列があります。

    前のモデルと同様に、アラート ポリシーを 1 つまたは 2 つ作成できます。ただし、アラート ポリシーの条件はより複雑です。プログラム A の呼び出し率がしきい値を超えた場合にインシデントを生成する条件では、ラベル値が A であるデータポイントのみを含むフィルタを使用する必要があります。

    このモデルのメリットの 1 つは、比率を簡単に計算できることです。たとえば、合計のうち、A の呼び出しによるものどれくらいかを判断できます。

  • 1 つの指標を使用して呼び出し数をカウントしますが、どのプログラムが呼び出しを行ったかを記録するのにラベルは使用しません。このモデルでは、2 つのプログラムのデータを結合する単一の時系列があります。ただし、2 つのプログラムのデータを分離することはできないため、目的に合ったアラート ポリシーを作成することはできません。

最初の 2 つの設計では、データ分析の要件を満たすことができますが、最後の設計では満たせません。

詳細については、ユーザー定義指標を作成するをご覧ください。

ユーザー定義指標の名前

ユーザー定義指標を作成するときは、指標タイプを表す文字列識別子を定義します。この文字列は、Google Cloud プロジェクトのユーザー定義指標間で一意である必要があり、指標をユーザー定義の指標として指定する接頭辞を使用する必要があります。Monitoring の場合、使用できる接頭辞は custom.googleapis.com/、workload.googleapis.com/、external.googleapis.com/user、external.googleapis.com/prometheus です。接頭辞の後には、収集内容を示す名前が続きます。指標の命名方法の詳細については、指標の命名規則をご覧ください。次に、指標タイプの 2 種類の識別子の例を示します。

    custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization

上記の例での接頭辞 custom.googleapis.com は、両方の指標がユーザー定義指標であることを示します。どちらの例も CPU 使用率を測定する指標用ですが、組織モデルが異なります。ユーザー定義指標が多くなることが予想される場合は、2 番目の例で使用されているような階層的な命名規則を使用することをおすすめします。

すべての指標タイプには、リソース名というグローバル一意識別子があります。指標タイプのリソース名の構成は以下のとおりです。

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

ここで、METRIC_TYPE は指標タイプの文字列識別子です。前の指標の例がプロジェクト my-project-id で作成されている場合、これらの指標のリソース名は次のようになります。

    projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

名前かタイプか:指標記述子では、name フィールドに指標タイプのリソース名が格納され、type フィールドに METRIC_TYPE 文字列が格納されます。

ユーザー定義指標のモニタリング対象リソースタイプ

データを時系列に書き込むときには、データの取得元を示す必要があります。データのソースを指定するには、データの取得元を示すモニタリング対象リソースタイプを選択し、それを使用して具体的な取得元を記述します。モニタリング対象リソースは、指標タイプの一部にはなりません。代わりに、データを書き込む時系列に、指標タイプへの参照とモニタリング対象リソースへの参照が含まれます。指標タイプはデータを表し、モニタリング対象リソースはデータが発信された場所を表します。

モニタリング対象リソースは、指標記述子を作成する前に検討してください。指標記述子に含める必要があるラベルは、使用するモニタリング対象リソースのタイプによって影響されます。たとえば、Compute Engine VM リソースには、プロジェクト ID、インスタンス ID、インスタンス ゾーンのラベルが含まれます。そのため、Compute Engine VM リソースに対して指標を記述する場合は、リソースラベルがインスタンス ID を含み、指標記述子にインスタンス ID のラベルは必要ありません。

指標の各データポイントは、モニタリング対象リソース オブジェクトと関連付ける必要があります。異なるモニタリング対象リソース オブジェクトからのポイントは、異なる時系列で保持されます。

ユーザー定義指標では、次のいずれかのモニタリング対象リソースタイプを使用する必要があります。

  • aws_ec2_instance: Amazon EC2 インスタンス。
  • dataflow_job: Dataflow ジョブ。
  • gae_instance: App Engine インスタンス。
  • gce_instance: Compute Engine インスタンス。
  • generic_node: ユーザー指定のコンピューティング ノード。
  • generic_task: ユーザー定義のタスク。
  • gke_container: GKE コンテナ インスタンス。
  • global: 他に適切なリソースタイプがない場合はこのリソースを使用します。ほとんどのケースでは、generic_node や generic_task の方が global より適切です。
  • k8s_cluster: Kubernetes クラスタ。
  • k8s_container: Kubernetes コンテナ。
  • k8s_node: Kubernetes ノード。
  • k8s_pod: Kubernetes Pod。

通常は、アプリケーション コードが実行されている物理リソースを表すモニタリング対象リソース オブジェクトを使用します。このアプローチにはいくつかのメリットがあります。

  • 単一のリソースタイプを使用する場合に比べてパフォーマンスが向上します。
  • 複数のプロセスが同じ時系列に書き込むことに起因する順不同データを回避します。
  • ユーザー定義指標データを、同じリソースから取得した他の指標データとグループ化できます。

global とジェネリック リソース

generic_task と generic_node のリソースタイプは、より個別な内容を扱う他のリソースタイプが適当でない場合に役立ちます。generic_task はタスクのようなリソース（たとえばアプリケーションなど）を定義する際、generic_node はノードのようなリソース（たとえば仮想マシンなど）を定義する際に便利です。どちらの generic_* タイプにも共通のラベルが用意されており、独自のリソース オブジェクトを定義できます。共通ラベルを指標フィルタに使うことで、集約や単純化が簡単に行えます。

一方、global リソースタイプには project_id ラベルと location ラベルしかありません。プロジェクト内に指標のソースが複数ある場合、同じ global リソース オブジェクトを使うと、指標データの競合や上書きが発生する可能性があります。

ユーザー定義指標をサポートする API メソッド

次の表では、Monitoring API のユーザー定義指標をサポートするメソッドと組み込み指標をサポートするメソッドを示します。

Monitoring API メソッド ユーザー定義指標
で使用		 組み込み指標
で使用
monitoredResourceDescriptors.get ○ ○
monitoredResourceDescriptors.list ○ ○
metricDescriptors.get ○ ○
metricDescriptors.list ○ ○
timeSeries.list ○ ○
timeSeries.create ○
metricDescriptors.create ○
metricDescriptors.delete ○

制限とレイテンシ

ユーザー定義指標とデータ保持に関連する上限については、割り当てと上限をご覧ください。

保存期間を超えて指標データを保持するには、Cloud Storage や BigQuery のような別の場所にデータを手動でコピーする必要があります。

ユーザー定義指標へのデータの書き込みに伴うレイテンシについて詳しくは、指標データのレイテンシをご覧ください。

次のステップ