このドキュメントでは、Monitoring API の timeSeries.list
メソッドを使用して指標データ(時系列データ)を読み取る方法について説明します。
timeSeries.list
メソッドを呼び出す方法はいくつかあります。
- このページの [プロトコル] タブを使用すると、フォームベースの API Explorer を使用できます。
- 言語固有のクライアント ライブラリを使用できます。
- Metrics Explorer を使用できます。
指標データを読み取るもう 1 つの方法は、timeSeries.query
メソッドにコマンドを送信することです。これには Monitoring Query Language(MQL)が必要です。このドキュメントでは、MQL または timeSeries.query
メソッドについては説明しません。これらのトピックの詳細については、timeSeries.query
を使用したデータの取得をご覧ください。
概要
timeSeries.list
メソッドを呼び出すたびに、1 つの指標タイプから任意の数の時系列が返されます。たとえば、Compute Engine を使用している場合、compute.googleapis.com/instance/cpu/usage_time
の指標タイプには VM インスタンスのそれぞれに個別の時系列があります。
指標と時系列の概要については、指標、時系列、リソースをご覧ください。
必要な時系列データを指定するには、timeSeries.list
メソッドに次の情報を指定します。
- 指標タイプを指定するフィルタ式。必要に応じて、時系列データの生成元のリソースを指定するか、時系列内の特定のラベルの値を指定することで、指標の時系列のサブセットを選択できます。
- 返されるデータの量を制限する時間間隔。
- (省略可)複数の時系列を組み合わせてデータの集計サマリーを生成する方法の指定。詳細および例については、データの集約をご覧ください。
時系列フィルタ
取得する時系列を指定するには、時系列フィルタを timeSeries.list
メソッドに渡します。
一般的なフィルタ コンポーネントは次のとおりです。
フィルタには、単一の指標タイプを指定する必要があります。次に例を示します。
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
ユーザー定義指標を取得するには、フィルタに指定する metric.type の接頭辞を
custom.googleapis.com
に変更するか、その他の実際に使用されている接頭辞がある場合は(external.googleapis.com
がよく使われています)それに変更します。フィルタには指標のディメンション ラベルの値を指定できます。どのようなラベルが存在するかは指標タイプによって決まります。次に例を示します。
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
前の式では、実際の指標オブジェクトではキーとして
labels
が使用されますが、正しいのはlabel
です。フィルタで選択できるのは、特定のモニタリング対象リソースタイプを含む時系列のみです。
resource.type = "gce_instance"
フィルタ コンポーネントを次のように結合して単一の時系列フィルタを作成できます。
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
(metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
すべての指標ラベルに値を指定しない場合、list
メソッドは、指定されていないラベルの値の組み合わせごとに 1 つの時系列を返します。このメソッドは、データが存在する時系列のみを返します。
期間
API を使用してデータを読み取る際、開始時刻と終了時刻を設定して、データを取得する時間間隔を指定します。API は、間隔 (start, end]
(開始時刻から終了時刻まで)からデータを取得します。
開始時間は終了時間より前にする必要があります。開始時間が終了時間より後の場合、API はエラーを返します。
特定のタイムスタンプを持つデータのみを取得する場合は、開始時刻を終了時間と同じに設定する、すなわち開始時間を設定しないでください。
時刻の表示形式
開始時刻と終了時刻は、RFC 3339 形式の文字列として指定する必要があります。 次に例を示します。
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
Linux の date -Iseconds
コマンドは、タイムスタンプを生成するのに便利です。
基本的なリスト取得操作
timeSeries.list
メソッドを使用すると、シンプルな元データだけでなく、高度に処理されたデータもを返すことができます。このセクションでは、使用可能な時系列を一覧表示する方法と、特定の時系列の値を取得する方法について説明します。
例: 使用可能な時系列のリストを取得する
次の例は、使用可能なすべてのデータを返すのではなく、フィルタに一致する時系列の名前と説明のみを含むリストを返す方法を示します。
プロトコル
timeSeries.list
リファレンス ページを開きます。[Try this method] ペインに、次のように入力します。
-
name: プロジェクトのパスを入力します。
projects/PROJECT_ID
-
filter: 指標タイプを指定します。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: 終了時間を入力します。
- interval.startTime: 開始時間を入力し、終了時間の 20 分前であることを確認します。
[標準パラメータを表示] をクリックし、[fields] に次のように入力します。
timeSeries.metric
-
name: プロジェクトのパスを入力します。
[実行] をクリックします。
次のサンプル出力は、2 つの異なる VM インスタンスの時系列を示します。
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
リクエストを curl
コマンド、HTTP リクエスト、または JavaScript として表示するには、API Explorer で fullscreen [Full screen] をクリックします。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、Monitoring API のトラブルシューティングをご覧ください。
例: 時系列データを取得する
この例では、特定の Compute Engine インスタンスについて 20 分間隔で記録された CPU 使用率の測定値を返します。返されるデータの量は、指標のサンプリング レートによって異なります。CPU 使用率は 1 分ごとにサンプリングされるため、このクエリの結果は約 20 データポイントになります。1 つの時系列に対して複数のデータポイントが返される場合、API は各時系列のデータポイントを新しい順に返します。このポイントの順序はオーバーライドされません。
プロトコル
このプロトコルの例では、返されたデータをレスポンス ボックスで扱いやすくするため、出力をさらに制限しています。
- フィルタ値は、時系列を単一の VM インスタンスに制限します。
- フィールド値は、時間と測定値の値のみを指定します。
これらの設定により、結果として返される時系列データの量が制限されます。
timeSeries.list
リファレンス ページを開きます。[Try this method] ペインに、次のように入力します。
-
name: プロジェクトのパスを入力します。
projects/PROJECT_ID
filter: 指標タイプを指定します。
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime: 終了時間を入力します。
interval.startTime: 開始時間を入力し、終了時間の 20 分前であることを確認します。
[標準パラメータを表示] をクリックし、[fields] に次のように入力します。
timeSeries.points.interval.endTime,timeSeries.points.value
-
name: プロジェクトのパスを入力します。
[実行] をクリックします。
このリクエストは次のような結果を返します。
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
リクエストを curl
コマンド、HTTP リクエスト、または JavaScript として表示するには、API Explorer で fullscreen [Full screen] をクリックします。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、Monitoring API のトラブルシューティングをご覧ください。
データの集約
timeSeries.list
メソッドでは、返された時系列データに対して統計的な集計や縮減を行うことができます。次のセクションでは、2 つの例を示します。詳細については、フィルタリングと集計: 時系列の操作をご覧ください。
例: 時系列のアライメントを行う
この例では、各時系列に含まれる 20 の個別の使用率測定値を 2 個の測定値に縮減します。つまり、20 分の時間間隔を 2 つの 10 分間に分け、それぞれの期間の平均使用率を算出します。まず各時系列のデータを 10 分間にアライメントしてから、各 10 分間の値の平均をとります。
このアライメント オペレーションには 2 つの利点があります。1 つはデータを平滑化すること、もう 1 つはすべての時系列データのデータを正確な 10 分の境界に合わせる(アライメントする)ことです。その後、アライメントされたデータをさらに処理できます。
プロトコル
timeSeries.list
リファレンス ページを開きます。[Try this method] ペインに、次のように入力します。
-
name: プロジェクトのパスを入力します。
projects/PROJECT_ID
-
aggregation.alignmentPeriod: 「
600s
」と入力します。 -
aggregation.perSeriesAligner:
ALIGN_MEAN
を選択します。 -
filter: 指標タイプを指定します。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: 終了時間を入力します。
- interval.startTime: 開始時間を入力し、終了時間の 20 分前であることを確認します。
-
[標準パラメータを表示] をクリックし、[fields] に次のように入力します。
timeSeries.metric,timeSeries.points
-
name: プロジェクトのパスを入力します。
[実行] をクリックします。
前の例で示した単一インスタンスのフィルタは削除されています。このクエリによって返されるデータ量は少ないため、1 つの VM インスタンスに制限する必要はありません。
次のサンプル結果には、3 つの VM インスタンスのそれぞれに対して 1 つの時系列が含まれます。各時系列には 2 つのデータポイント(10 分のアライメント期間の平均 CPU 使用率)があります。
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
リクエストを curl
コマンド、HTTP リクエスト、または JavaScript として表示するには、API Explorer で fullscreen [Full screen] をクリックします。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、Monitoring API のトラブルシューティングをご覧ください。
例: 時系列を横断的に縮減する
この例では前の例を拡張し、3 つの VM インスタンスのアライメントされた時系列を統合して、すべてのインスタンスの平均 CPU 使用率を含む単一の時系列を作成します。
プロトコル
timeSeries.list
リファレンス ページを開きます。[Try this method] ペインに、次のように入力します。
-
name: プロジェクトのパスを入力します。
projects/PROJECT_ID
-
aggregation.alignmentPeriod: 「
600s
」と入力します。 -
aggregation.perSeriesAligner:
ALIGN_MEAN
を選択します。 -
aggregation.crossSeriesReducer:
REDUCE_MEAN
を選択します。 -
filter: 指標タイプを指定します。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: 終了時間を入力します。
- interval.startTime: 開始時間を入力し、終了時間の 20 分前であることを確認します。
-
[標準パラメータを表示] をクリックし、[fields] に次のように入力します。
timeSeries.metric,timeSeries.points
-
name: プロジェクトのパスを入力します。
[実行] をクリックします。
次のサンプル結果には、単一の時系列と 2 つのデータポイントが含まれます。各ポイントは、対象期間中の 3 つの VM インスタンスの CPU 使用率の平均値です。
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
リクエストを curl
コマンド、HTTP リクエスト、または JavaScript として表示するには、API Explorer で fullscreen [Full screen] をクリックします。
C#
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Monitoring への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
問題がある場合は、Monitoring API のトラブルシューティングをご覧ください。
次のステップ
- 指標データの保持とレイテンシについて学習する。
- フィルタリングと集計: 時系列の操作について学習する。