MQL のコードエディタを使用する

このセクションでは、Monitoring Query Language（MQL）用のコードエディタの機能について説明します。このエディタは Google Cloud コンソールで使用でき、有効な MQL クエリを作成するための候補、エラー検出などがサポートされます。

このページでは MQL 言語については説明しません。一連の例と言語の詳細については、例と MQL 言語についてをご覧ください。MQL リファレンスでは、言語の全体的なリファレンスが提供されます。

コードエディタへのアクセス

Metrics Explorer の使用時にコードエディタにアクセスするには、次の手順を行います。

Google Cloud コンソールのナビゲーションパネルで [モニタリング] を選択し、次に [Metrics Explorer] を選択します。
Metrics Explorer に移動
クエリビルダーペインのツールバーで、名前が [MQL] または [PromQL] のボタンを選択します。
[言語] 切り替えで [MQL] が選択されていることを確認します。言語切り替えボタンは、クエリの書式設定を行うのと同じツールバーにあります。

ダッシュボードでグラフを作成する際に、同様の手順を使用して、コードエディタにアクセスします。

コードエディタの使用

コードエディタを使用するには、テキストボックスにクエリを入力して [Run Query] をクリックします。

コードエディタ内の MQL クエリ。

オートコンプリート

クエリを入力すると、エディタに構文的に有効な完了のリストが表示されます。Control+Space を押すとオートコンプリートメニューを手動で表示できます。Escape を押すと非表示にできます。

オプションのリスト内を移動するには、矢印キーを使用します。Enter を押すと、選択した項目が挿入されます。

使用可能なすべての選択肢に共通のプレフィックスを挿入するには、Tab を押します。

エラーメッセージ

エラーメッセージはエディタペインの下部に表示されます。

クエリにオートコンプリートの候補に干渉するエラーがある場合は、入力時にエラーメッセージが表示されます。それ以外の場合は、クエリを実行するとエラーメッセージが表示されます。

コードの折りたたみ

このエディタでは、クエリのセグメントを折りたたみます。この機能により、クエリのセグメントを折りたたむことができるため、一時的に非表示にできます。

次のスクリーンショットに示すように、エディタでは行番号の横にキャレットが付された、折りたたみ可能なセグメントが表示されます。

コードエディタは、キャレット付きの折りたたみコードを示します。

検索と置換

エディタは、検索と置換の機能をサポートしています。クエリ内のキーワードを検索し、必要に応じて置換するには、Control+F（Mac では Command+F）を押します。次のスクリーンショットで、その機能を示します。

コードエディタは検索置換機能をサポートしています。

エディタコントロール

エディタの 2 つのコントロールで、クエリの操作方法が決定されます。

デフォルトでは、[Run Query] をクリックした場合にのみクエリが実行されます。コードエディタは、クエリの入力と同時にクエリを自動的に実行するように設定できますが、デフォルトではこのオプションが無効にされています。

自動実行オプションを有効にするには、[Auto-run] トグルを使用します。このオプションが有効になると、エディタは次のように動作します。

[Run Query] ボタンは表示されません。
入力時にエラーメッセージが継続して表示されます。
カーソルが不完全ではあるものの、エラーがないクエリの末尾にある場合は、エディタのコントロールバーに黄色の三角形が表示されます。表示スペースがある場合は、[不完全なクエリ] というテキストも表示されます。

コードエディタは、不完全なクエリの評価を試みません。

コードエディタとグラフ領域の間にはグラブバーもあります。このバーを使用して、2 つの領域の相対的なサイズを変更します。

グラフを保存する

Metrics Explorer から

Metrics Explorer のコードエディタから、グラフをダッシュボードに保存することもできます。グラフを保存するには:

自動実行オプションを有効にしていない場合は、グラフを保存する前に [Run Query] をクリックしてクエリを実行します。最初にクエリを実行しない場合、コードエディタは最後に実行したクエリを保存します。
[Save Chart] をクリックします。ダイアログボックスに、グラフを保存するとクエリが厳密な形式に置き換えられるという内容のメッセージが表示されます。詳細については、厳密な形式のクエリをご覧ください。
グラフの保存を続行するには:
1. グラフにわかりやすいタイトルを付けます。
2. 新しいグラフを表示する目的のダッシュボードを選択します。
3. ダイアログで [Save]をクリックします。

ダッシュボードから

ダッシュボードに追加するグラフを保存する方法は次のとおりです。

グラフにわかりやすいタイトルを付けます。
自動実行オプションを有効にしていない場合は、グラフを保存する前に [Run Query] をクリックしてクエリを実行します。最初にクエリを実行しない場合、コードエディタは最後に実行したクエリを保存します。
[保存] をクリックします。ダイアログボックスに、グラフを保存するとクエリが厳密な形式に置き換えられるという内容のメッセージが表示されます。詳細については、厳密な形式のクエリをご覧ください。
ダイアログで [保存] をクリックしてグラフを保存し、ダッシュボードに戻ります。

コードエディタを終了する

グラフまたは条件を保存せずにコードエディタを終了するには、[ クエリセレクタウィジェットに戻る] をクリックします。エディタ内のクエリテキストは破棄されますが、クリップボードへの保存を選択することも可能です。

厳密なフォームでクエリを表示する

コードエディタの使用時に厳密な形式でクエリを表示するには、 [その他のオプション] をクリックして [厳密なフォームを表示] を選択します。

詳細については、厳密な形式のクエリをご覧ください。

期間、グラフ、コードエディタ

アラートポリシーの条件で使用される MQL クエリを除き、コードエディタの MQL クエリには期間を含める必要があります。期間には、クエリの一部として返されるデータのサブセットを指定します。期間は、グラフの期間セレクタを使用して暗黙的に、または MQL クエリテキストで明示的に表すことができます。

デフォルトでは、期間セレクタは 1 時間に設定されています。

グラフの期間を変更するには、期間セレクタを使用します。たとえば、過去 1 週間のデータを表示するには、期間セレクタから [過去 1 週間] を選択します。開始時間と終了時間を指定したり、表示時間を指定することもできます。

コードエディタでアラートポリシーを作成する方法については、MQL アラートポリシーの作成をご覧ください。

期間の選択にグラフ設定を使用する

グラフのタイムセレクタを使用して、クエリの期間を設定できます。このセレクタは、期間を設定するためのデフォルトの方法です。期間を変更するには、グラフで別の時間オプションを選択します。たとえば、1 週間を選択した場合、クエリは現在から 1 週間前までのデータを返します。

MQL では、グラフ指定の時間を使用できます。

このデフォルトのメカニズムを使用すると、クエリのテキストで明示的な時間範囲を指定する必要はありません。グラフの値は暗黙的に使用されます。

時間の選択に `within` を使用する

within オペレーションを使用することで、クエリでクエリの期間を明示的に指定できます。このオペレーションにより、返されるデータの範囲が決まります。クエリに within オペレーションが含まれている場合、グラフの時間選択オプションは無効となり、クエリで指定された期間が使用されます。

クエリから明示的な within オペレーションを削除すると、グラフのオプションが自動的に再度有効になり、クエリに常に期間が含まれるようになります。

API メソッド timeSeries.query を使用してクエリを発行する場合は、明示的な時間の選択を使用する必要があります。詳細については、Monitoring API からの MQL の使用をご覧ください。

期間設定と保存済みグラフ

MQLを使用してグラフを作成しそのグラフをダッシュボードに保存すると、クエリの2つのことが起こります。

エディタで指定したクエリは、簡潔または厳密な形式に変換されます。変換によってクエリの意味が変更されることはありませんが、完全な列名やアライメントオペレーションなど、クエリで想定されている明示的な処理が行われます。詳細については、厳密な形式のクエリをご覧ください。
クエリの時間範囲の選択が削除されます。ダッシュボードのグラフではタイムセレクタを共有し、そのセレクタへの変更はダッシュボード上のすべてのグラフに適用されます。したがって、元のクエリの期間セレクタは不要になります。

ダッシュボードの管理とグラフの編集については、カスタムダッシュボードを管理するをご覧ください。

クエリ、アライメント、表示期間

MQL には、期間を指定するいくつかのオペレーションがありますが、これらは混乱を招く可能性があります。クエリの範囲に関連するオペレーションは次のとおりです。

within: クエリ出力ウィンドウを指定します。このオペレーションで、返されるデータの量が決まります。たとえば、within 1h を指定すると、タイムスタンプが過去 1 時間以内のポイントのみを生成します。そのため、このオペレーションはグラフのタイムセレクタオプションをオーバーライドします。
次のオペレーションは、出力テーブルのアラインメント期間に関連しています。どちらも、入力としてアラインメントされたテーブルを要求するか、デフォルトを指定します。
- every: 整列されたテーブル出力の期間を指定します。
- window: アライメント操作のウィンドウを指定します。
どちらの場合も、align オペレーションで明示的なアラインメントウィンドウが指定された場合、window オペレーションに指定された期間と一致する必要があります。delta アライメント関数の場合、アライメントウィンドウと期間は同じである必要があります。明示的なアラインメントウィンドウが指定されている場合、every オペレーションが合意する必要があります。いずれの場合も、アライメントウィンドウは少なくともアライメント期間と同じ大きさである必要があります。そうでない場合、入力データは無視されます。

MQL には、グラフの出力ポイントの期間を指定する graph_period オペレーションもあります。このオペレーションは、出力がサードパーティソフトウェアによってグラフ化されている API に与えられたクエリで役立ちます。Monitoring のグラフ作成ソフトウェアは、クエリの graph_period オペレーションを無視し、出力グラフの時間幅に応じてポイントの期間を設定します。

Monitoring のグラフでは、グラフの期間はグラフの時間範囲セレクタの値と、グラフが表示できるポイントの最大数に基づいて設定されます。たとえば、1 週間を選択した場合、グラフの期間は 1 時間になります。ダッシュボードのグラフの場合、グラフの期間を表示するには、 [クエリの統計データ] をクリックします。

クエリのアラインメント期間とグラフの期間の関係に応じて、グラフの外観が変わる場合があります。この関係については、次のセクションで説明します。

最小 / 最大バンド

クエリのアラインメント期間がグラフの期間に近い場合、グラフ化された各時系列は 1 本の線で表されます。クエリのアラインメント期間がグラフのグラフ期間の半分未満の場合、そのグラフの線の周りに影付きの領域が表示されます。この領域は最小 / 最大バンドと呼ばれ、平均値を生成した値の範囲を示します。

たとえば、次のような単純な MQL クエリがあるとします。

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

このクエリは、1 時間のアラインメント期間で、ゾーンごとの VM の平均 CPU 使用率を返します。

グラフのタイムセレクタが 1 週間に設定されている場合、グラフの期間は 1 時間となり、これがチップに表示されます。このクエリの例では、グラフの期間とアラインメント期間は同じです。このクエリを実行すると、次のようなグラフが生成されます。

折れ線グラフのアラインメント期間とグラフ期間が等しい場合、線のみが表示されます。

たとえば、前のクエリで every オペレーションに渡されたアライメント期間を 1h から 1m に変更すると、最小 / 最大バンドを含むグラフが生成されます。

折れ線グラフのアライメント期間がグラフ期間の半分未満の場合、線と最小 / 最大バンドが表示されます。

グラフの線は、グラフの 1 週間の選択に基づいて、1 時間のグラフ期間でグラフ化されるため、線は前の例の線と同じになります。ただし、クエリは 1 分ごとにポイントを生成するため、最小 / 最大バンドは、各 1 時間のグラフポイントに分類されるクエリからの 1 分の値の範囲を示します。

every オペレーションを省略した場合、デフォルトのクエリアラインメント期間はアライメントウィンドウの値になります。アライメントウィンドウが指定されていない場合は 1 分になります。

MQL ベースのアラートポリシー

MQL とコードエディタを使用して、アラートポリシーで使用するクエリを作成することもできます。

Google Cloud コンソールから MQL ベースのアラートポリシーを作成するには、アラートポリシーの管理で説明されているポリシーを作成するための通常の手順に従いますが、アラートポリシーの条件を作成する場合は、フォームベースの指標セレクタの代わりにコードエディタを使用します。

詳細については、MQL アラートポリシーの作成をご覧ください。

クエリコンバージョン

グラフの指標セレクタや Metrics Explorer を使用してクエリを作成し、そのクエリを MQL に変換できます。対応する MQL クエリがエディタに表示されます。

Metrics Explorer の使用時に、メニューで作成されたクエリを MQL に変換する手順は次のとおりです。

クエリビルダーペインのツールバーで、名前が [MQL] または [PromQL] のボタンを選択します。
[言語] 切り替えで [MQL] が選択されていることを確認します。言語切り替えボタンは、クエリの書式設定を行うのと同じツールバーにあります。

フォームベースのクエリを MQL に変換するには、ダッシュボードでグラフを表示しているときに [MQL] をクリックします。

「Compute Engine VM インスタンスから CPU 使用率を取得する」などの非常に単純なリクエストについて考えてみましょう。このクエリには、gce_instance モニタリング対象リソースタイプと compute.googleapis.com/instance/cpu/usage_time 指標タイプが含まれています。

次のスクリーンショットは、フォームベースの指標セレクタにおけるクエリを示しています。

指標セレクタにおける指標とリソースタイプの選択。

指標とモニタリング対象リソースのタイプが手動で入力されています。他のフィールドはすべてデフォルト値になります。

次のスクリーンショットは、フォームベースの選択を MQL クエリに変換した結果を示しています。

エディタに、フォームの値を MQL に変換した結果が表示される。

MQL は、指定された指標とリソースタイプの時系列を取得し、1 分間隔でレート調整を実行します。変換されたクエリは厳格形式です。