Monitoring API からの MQL の使用

このページでは、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....
```

Monitoring API からの MQL の使用

API からの MQL の使用

timeSeries.query を使用したデータの取得

グラフの作成

MQL ベースのグラフの作成

グラフの作成

アラート ポリシーの条件の作成

アラート ポリシーの作成

通知ポリシーの作成

curl の呼び出し

`timeSeries.query` を使用したデータの取得

アラートポリシーの条件の作成

アラートポリシーの作成

`curl` の呼び出し