このページでは、Monitoring Query Language(MQL)クエリを Cloud Monitoring API に提供する方法について説明します。
このページでは、MQL クエリの作成については説明しません。一連のサンプルクエリについては、例をご覧ください。MQL リファレンスでは、言語の全体的なリファレンスが提供されます。
MQL ベースのアラート ポリシーの一般的な情報については、MQL のアラート ポリシーをご覧ください。
API からの MQL の使用
Monitoring API の次のプレイスで、MQL クエリを提供できます。
MQL を使用して時系列データを選択して操作するには、
timeSeries.query
メソッドを呼び出します。 例については、timeSeries.query
の使用をご覧ください。グラフの時系列データを選択して操作するには、
dashboards.create
メソッドを呼び出すときにTimeSeriesQuery
仕様にクエリを提供します。例については、グラフの作成をご覧ください。アラート ポリシーで MQL ベースの条件を作成するには、
alertPolicies.create
を呼び出す際に、アラート ポリシーの条件をMonitoringQueryLanguageCondition
条件タイプで記述してください。例については、アラート ポリシーの条件の作成をご覧ください。
timeSeries.query
を使用したデータの取得
timeSeries.query
メソッドを使用して、MQL クエリで API から時系列データを取得します。
timeSeries.query
メソッドは、JSON で次のような最小限の構造を取ります。
{ "query": string }
query
フィールドの値には、次の単純なクエリに示すように、MQL で文字列を指定します。
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m" }
クエリによって非整列出力テーブルが作成される場合は、API を直接呼び出すときに within
テーブル オペレーションを使用して期間を指定する必要があります。Metrics Explorer などのグラフツールはデフォルトのクエリ期間を提供します。次の JSON スニペットのクエリは、Metrics Explorer の MQL コードエディタで機能しますが、API に直接指定すると失敗します。
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)" }
上記のクエリに within
テーブル オペレーションを追加することで、上記の例を API に直接指定できます。
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h" }
API を試すには、timeSeries.query
リファレンス ページの API Explorer ツールを使用できます。API Explorer ツールの概要については、API Explorer をご覧ください。
API を試すもう 1 つの方法は、クエリをテキスト ファイルに入力し、curl
を使用してクエリを実行することです。次の例では、ファイル query.json
のクエリを timeSeries.query
メソッドに渡します。
curl -d @query.json -H "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/json" -X POST \ https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query
curl
の使用の詳細については、curl
の呼び出しをご覧ください。
成功すると、クエリはリクエストされた時系列を含むテーブルを返します。このテーブルは以下の 2 つのコンポーネントに分かれています。
timeSeriesDescriptor
は、テーブル内のラベルキー、ラベル値、データポイントを表します。これにはデータは含まれておらず、データを記述するだけです。timeSeriesData
には、時系列記述子で説明されたデータが含まれます。このデータはペアの配列として表示されます。- ペアの最初の項目の
labelValues
は、時系列記述子にリストされたラベルの値のセットを記録します。 - 2 番目の
pointData
は、値とタイムスタンプのペアのエンベッデド アレイであり、指定されたラベル値のセットで収集されたデータを表します。
- ペアの最初の項目の
フォーマットを少し変更したレスポンスは次のようになります。
[{ "timeSeriesTable": { "timeSeriesDescriptor": { "labelDescriptors": [ { "key": "resource.project_id" }, { "key": "resource.zone" }, { "key": "resource.instance_id" }, { "key": "metric.instance_name" } ], "valueDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ], "pointDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ] }, "timeSeriesData": [ { "labelValues": [ { "stringValue": "632526624816" }, { "stringValue": "us-central1-a" }, { "stringValue": "5106847938297466291" }, { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" } ], "pointData": [ { "values": [ { "doubleValue": 0.063896992710942874 } ], "timeInterval": { "startTime": "1969-12-31T23:59:59.999999Z", "endTime": "2020-03-02T20:17:00Z" } }, { ... additional value/timestamp pairs ...} ] }, { ... additional labelValue/pointData pairs ...}, ] }
グラフの作成
dashboards.create
メソッドを使用して、ダッシュボードとそこに含まれるグラフをプログラムで作成できます。
MQL ベースのグラフと他のグラフの作成の唯一の違いは、グラフのデータセットを作成するために使用する TimeSeriesQuery
クエリのタイプです。
MQL ベースのグラフの作成
MQL クエリの場合、クエリをグラフの DataSet
配列の timeSeriesQueryLanguage
文字列フィールドの値として使用します。
以下は、MQL を含む簡単なダッシュボード定義です。
{ "displayName": "Dashboard for MQL chart (API)", "gridLayout": { "widgets": [ { "title": "Min/Max Compute Engine CPU utilization", "xyChart": { "dataSets": [ { "timeSeriesQuery": { "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union" }, "plotType": "LINE", } ], "timeshiftDuration": "0s", "yAxis": { "label": "y1Axis", "scale": "LINEAR" }, "chartOptions": { "mode": "COLOR" } } } ] } }
これにより、プロジェクトに「Dashboard for MQL chart (API)」というタイトルのダッシュボードが作成されます。ダッシュボードには「Min/Max Compute Engine CPU Utilization」と呼ばれるグラフが含まれます。これは、最高値と最低値の 2 つの線を表しています。
このクエリ例の詳細については、選択を union
で組み合わせるをご覧ください。
グラフの作成
ダッシュボードの JSON をファイルに入れて gcloud beta monitoring dashboards create
に渡すか、curl
を使用して https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards
に送信できます。その他の例については、ダッシュボードの作成をご覧ください。curl
の使用の詳細については、curl
の呼び出しをご覧ください。
グラフとダッシュボードの作成に関する全般情報については、API によるダッシュボードの管理をご覧ください。参考情報については、Dashboards
をご覧ください。
アラート ポリシーの条件の作成
alertPolicies.create
メソッドを使用して、アラート ポリシーをプログラムで作成します。
MQL ベースのアラート ポリシーの作成と他のアラート ポリシーの作成の唯一の違いは、使用する Condition
のタイプです。それ以外は、他のアラート ポリシーと同様にポリシーを作成します。
以下は、Compute Engine の CPU 使用率が 15% を超えたかどうかをテストするアラート ポリシー条件に対するシンプルな MQL クエリを示しています。
fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'
MQL condition
アラート オペレーションの詳細については、MQL のアラート ポリシーをご覧ください。
アラート ポリシーの作成
MQL クエリに基づいてアラート ポリシーを作成するには、AlertPolicy
条件タイプ MonitoringQueryLanguageCondition
を使用します。MonitoringQueryLanguageCondition
の構造は次のとおりです。
{ "query": string, "duration": string, "trigger": { object (Trigger) } }
query
フィールドの値は、MQL アラートクエリ文字列で、簡潔または厳密な形式で指定します。このドキュメントの例は簡約な形式です。厳密な形式の詳細については、厳密な形式のクエリをご覧ください。
duration
フィールドは、アラート ポリシーがトリガーされるまでに、クエリの各評価で true
値が生成されるまでの時間を指定します。詳細については、指標ベースのアラート ポリシーの動作をご覧ください。
値は時間(分)で、秒単位で表されます。たとえば、600s
は 10 分の期間です。
trigger
フィールドは、duration
期間中に条件を満たす必要がある時系列の数をカウントまたはパーセンテージで指定します。デフォルト値は 1 です。詳細については、Trigger
をご覧ください。
アラートクエリ(期間 10 分、トリガー カウントが 1)の例の場合、構造は次のようになります。
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 } }
この構造を条件内の conditionMonitoringQueryLanguage
フィールドの値として使用します。この値は、アラート ポリシー構造に埋め込まれます。これらの構造の詳細については、AlertPolicy
をご覧ください。
JSON 内で MonitoringQueryLanguageCondition
条件を使用する完全な最小ポリシーを以下に示します。
{ "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)", "combiner":"OR", "conditions":[ { "displayName":"MQL-based utilization condition, API", "conditionMonitoringQueryLanguage": { "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 }, }, } ], }
通知ポリシーの作成
ポリシーを作成するには、アラート ポリシー JSON をファイルに追加し、ファイルを gcloud alpha monitoring policies create
に渡すか、curl
を使用して https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies
に送信します。
アラート ポリシー用の Monitoring API の詳細については、API によるアラート ポリシーの管理をご覧ください。
curl
の使用の詳細については、curl
の呼び出しをご覧ください。
curl
の呼び出し
各 curl
呼び出しには一連の引数が含まれ、API リソースの URL がそれに続きます。一般的な引数には、Google Cloud プロジェクト ID と認証トークンが含まれます。これらの値は、ここでは PROJECT_ID
および TOKEN
環境変数で表されます。
HTTP リクエストのタイプ(たとえば、-X DELETE
)を指定する場合など、他の引数を指定する必要がある場合もあります。デフォルトのリクエストは GET
であるため、例では指定していません。
各 curl
呼び出しは、次の一般的な構造をしています。
curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
curl
を使用するには、プロジェクト ID とアクセス トークンを指定する必要があります。入力とエラーを減らすために、これらを環境変数に入れて curl
に渡すことができます。
これらの変数を設定するには、次のことを行います。
指標スコープのスコープ プロジェクト ID を保持する環境変数を作成します。次の手順では、変数
PROJECT_ID
を呼び出します。PROJECT_ID=a-sample-project
Google Cloud CLI に対して認証を行います。
gcloud auth login
省略可。各
gcloud
コマンドでのプロジェクト ID の指定を不要にするには、gcloud CLI を使用してプロジェクト ID をデフォルトとして設定します。gcloud config set project ${PROJECT_ID}
認証トークンを作成し、環境変数にキャプチャします。次の手順では、変数
TOKEN
を呼び出します。TOKEN=`gcloud auth print-access-token`
アクセス トークンは定期的に更新する必要があります。動作していたコマンドに急に未認証と報告された場合は、このコマンドを再発行します。
アクセス トークンがあることを確認するには、
TOKEN
変数をエコーします。echo ${TOKEN} ya29.GluiBj8o....