このドキュメントでは、ユーザー定義指標を作成する方法と、Cloud Monitoring API を使用してこの指標データを書き込む方法について説明します。 ユーザー定義指標は、組み込みの Cloud Monitoring 指標と同じ要素を使用します。
- データポイントのセット。
- データポイントが何を表しているかを示す指標タイプ情報。
- モニタリング対象リソース情報。データポイントの発生場所がわかります。
ユーザー定義指標(カスタム指標とも呼ばれます)は、組み込み指標と同じ方法で使用できます。つまり、この指標のデータについて、グラフやアラートを作成できます。
ログベースの指標は、ユーザー定義指標のクラスですが、Cloud Monitoring API を使用して作成できません。ログベースの指標はログエントリから指標データを取得しますが、Monitoring API はログエントリから指標データを抽出する方法を指定できません。代わりに、Cloud Logging を使用してログベースの指標を作成します。ログベースの指標を作成すると、Logging によってこのドキュメントで説明されている構造が作成され、指標データが Cloud Monitoring に送信されます。ログベースの指標の作成については、次のドキュメントをご覧ください。
アプリケーションを計装化する場合は、ベンダー固有またはプロダクト固有の API やクライアント ライブラリではなく、OpenTelemetry などのオープンソースの計装化フレームワークを使用することをおすすめします。アプリケーションの計装の詳細については、計装とオブザーバビリティをご覧ください。
始める前に
すべての指標の基礎となる構造については、指標、時系列、リソースをご覧ください。
Cloud Monitoring を使用するには、課金を有効にした Google Cloud プロジェクトが必要です。必要に応じて、次のことを行います。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Monitoring API が有効になっていることを確認します。詳細については、Monitoring API の有効化をご覧ください。
Google Cloud の外部で実行されているアプリケーションの場合、Google Cloud プロジェクトでアプリケーションを認証する必要があります。通常は、プロジェクト用のサービス アカウントを作成し、環境変数を構成することによって、認証を構成します。
サービス アカウントの作成については、認証の開始をご覧ください。
ユーザー定義指標タイプを作成する
ユーザー定義指標を作成するには、指標に関するさまざまな情報を指定する MetricDescriptor
オブジェクトを定義するか、指標データを書き込みます。指標データを書き込むと、Monitoring では、提供されたデータの構造に基づいて指標記述子が作成されます。指標記述子の設計については、ユーザー定義指標の指標記述子をご覧ください。
指標記述子の自動作成
該当のユーザー定義指標の指標記述子が存在しない場合に指標データを書き込むと、指標記述子が自動的に作成されます。 ただし、この新しい指標記述子は、必要なものとは正確に一致しない可能性があります。指標記述子の自動作成には、いくつかの仮定とデフォルトが伴います。
timeSeries.create
の呼び出しに含まれる TimeSeries
オブジェクトが、存在しない 指標タイプ名 を指定する Metric
オブジェクトを参照する場合、Cloud Monitoring は新しいMetricDescriptor
を作成します。Cloud Monitoring は、次のルールを使用して MetricDescriptor
に値を入力します。
type
:Metric
オブジェクトのtype
フィールドからコピーされます。name
: 名前は、メソッド呼び出しで指定されたプロジェクト ID とMetric
オブジェクトのtype
の値から作成されます。labels
:Metric
オブジェクトで使用されるラベル。新しい指標記述子の各ラベル記述子には次のフィールドがあります。key
:Metric
オブジェクト内のラベルキーvalueType
:STRING
description
: 未設定
metricKind
:TimeSeries
オブジェクトのmetricKind
パラメータを指定しない限り、指標の種類はGAUGE
に設定されます。metricKind
を指定すると、新しい指標はその種類になります。GAUGE
とCUMULATIVE
の種類のみ指定できます。valueType
: 値型は、書き込まれるPoint
の型指定された値から取得されます。値型は、BOOL
、INT64
、DOUBLE
、DISTRIBUTION
のいずれかにする必要があります。TimeSeries
のvalueType
フィールドで、値型を指定する場合は、その型がPoint
の型と一致する必要があります。unit
: 未設定description
:"Auto created custom metric."
displayName
: 未設定
1 回の timeSeries.create
の呼び出しに、存在しない同じ指標タイプを参照する複数の TimeSeries
オブジェクトを含めることができます。その場合、新しい指標記述子のラベルは、この create
の呼び出しにおけるすべての時系列の Metric
オブジェクトのラベルすべてのユニオンになります。
次のステップ: ユーザー定義指標を書き込むをご覧ください。
手動での指標記述子の作成
指標記述子を作成するには、次のようにします。
指標記述子の構造を決定します。こうした選択では、組み込まれた指標を閲覧することや、その時系列データを見ることが、判断の参考になります。
指標データの書き込み対象となるモニタリング対象リソースを決定します。次のリストから選択します。
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。
MetricDescriptor
オブジェクトを作成して、metricDescriptors.create
メソッド呼び出しの引数として渡します。
metricDescriptors.create
を呼び出す際に既存の指標記述子と同じタイプ名を使用すると、通常はエラーになります。ただし、新しい MetricDescriptor
オブジェクトのすべてのフィールドが既存の記述子のフィールドと完全に一致していればエラーになりませんが、効果はありません。
次の例では、ゲージ指標を作成します。
プロトコル
指標記述子を作成するには、metricDescriptors.create
メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。
metricDescriptors.create
のサンプル パラメータを次に示します。
- 名前 (URL):
projects/[PROJECT_ID]
リクエスト本文: 次のような
MetricDescriptor
オブジェクトを渡します。{ "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
[PROJECT_ID
] の部分を実際のプロジェクト ID に置き換えて、これらの値をウィジェットのフィールドに入力します。
[Execute] ボタンをクリックしてメソッドを実行します。
新しい指標を作成する際、MetricDescriptor
の name
フィールドは無視され、省略できます。create
メソッドから返される新しい指標記述子では、name
フィールドに名前が設定されています。この例では、名前は次のようになります。
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
たとえば、指標の記述子を取得する場合などに、この名前を使用します。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。
次のステップ: ユーザー定義指標を書き込むをご覧ください。
ユーザー定義指標を書き込む
データを定義することができるのは、ユーザー定義指標の指標タイプのみです。データを書き込むには、timeSeries.create
メソッドを使用します。時系列が存在する場合は、このメソッドによって既存の時系列に新しいデータポイントが追加されます。時系列が存在しない場合、このメソッドは、時系列を作成してデータを追加します。
データポイントを書き込むには、TimeSeries
オブジェクトのリストを timeSeries.create
に渡します。リストの最大サイズは 200 で、リスト内の各オブジェクトに異なる時系列を指定する必要があります。
metric
フィールドとresource
フィールドの値は、特定のTimeSeries
オブジェクトを同定します。このフィールドは、データの指標タイプと、データの収集元のモニタリング対象リソースを表します。metricKind
フィールドとvalueType
フィールドは省略します。データポイントを書き込むときには無視されます。各
TimeSeries
オブジェクトにはPoint
オブジェクトを 1 つだけ含める必要があります。- ポイントの値と時間間隔は指標タイプの定義と一致していなければなりません。さまざまな種類の指標の時間間隔については、
TimeInterval
をご覧ください。 - ポイントの時間間隔は、時系列にすでに存在するすべてのポイントより後である必要があります。
- 時間間隔の終了時刻は、過去 25 時間以内または未来 5 分以内でなければなりません。
- ポイントの値と時間間隔は指標タイプの定義と一致していなければなりません。さまざまな種類の指標の時間間隔については、
同じ時系列に複数のポイントを書き込むには、それぞれのポイントごとに
timeSeries.create
メソッドを呼び出します。5 秒ごとに 1 つのポイントよりも速く、1 つの時系列にデータを書き込むことはできません。異なる時系列にデータポイントを追加する場合、レート制限はありません。
プロトコル
指標データを書き込むには、timeSeries.create
メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。
手動での指標記述子の作成で作成した stores/daily_sales
指標にポイントを書き込むには:
timeSeries.create
のリファレンス ページに移動します。- 下記のパラメータを API Explorer ウィジェットに供給します。
- [Execute] ボタンをクリックします。
次のサンプル パラメータを使用します。
- 名前:
projects/[PROJECT_ID]
リクエスト本文: この中に
TimeSeries
オブジェクトのリストがあります。次のサンプルでは、リストに時系列が 1 つだけ含まれています。{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。
ユーザー定義指標を削除する
ユーザー定義指標を削除するには、その指標記述子を削除します。 Google Cloud プロジェクトに保存されている時系列データは削除できません。ただし、指標記述子を削除すると、データにアクセスできなくなります。データは期限切れになり、データ保持ポリシーに従って削除されます。
組み込み指標の指標記述子は削除できません。
指標記述子を削除するには、metricDescriptors.delete
メソッドを呼び出します。
プロトコル
指標記述子を削除するには、metricDescriptors.delete
メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。
手動での指標記述子の作成で作成した stores/daily_sales
指標を削除するには、次のようにします。
metricDescriptors.delete
のリファレンス ページに移動します。指標記述子の名前を API Explorer ウィジェットに供給します。
名前:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
[Execute] ボタンをクリックします。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。
ユーザー定義指標を変更する
ユーザー定義指標を変更するには、指標を定義する MetricDescriptor
オブジェクトを更新する必要があります。
サポートされている変更はラベルの追加のみです。
既存のユーザー定義指標にラベルを追加するには、timeSeries.create
メソッドを使用して、時系列データを含む新しいラベルを追加します。書き込もうとしているラベルが有効で、ラベルの総数が 30 未満の場合、ラベルは指標記述子に追加されます。
その後は、あたかもそのラベルが最初から存在していたかのように時系列データが書き込まれます。
新しいラベルを追加すること以上の変更を加える場合は、指標記述子を削除して再作成する必要があります。この場合、それまでに収集された古い指標記述子の時系列データはすべて失われます。詳細については、ユーザー定義指標を削除するをご覧ください。
指標の名前は変更できません。