クエリエディタの使用

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

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

クエリエディタにアクセスする

クエリエディタには、Google Cloud Console の次のページからアクセスできます。

  • Metrics Explorer
  • ダッシュボードの作成時にグラフを追加する

次のスクリーンショットでは、例として Metrics Explorer を使用しています。

[リソースのタイプと指標] ボックスのすぐ上に、MQL セレクタが表示されます。

クエリエディタを表示するには、[指標] タブの [ クエリエディタ] をクリックします。次のスクリーンショットは、クエリエディタを示しています。

MQL クエリエディタ

クエリエディタを使用する

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

クエリエディタで MQL クエリを実行します。

オートコンプリート

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

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

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

エラー メッセージ

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

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

コードの折りたたみ

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

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

Query Editor は、キャレット付きの折りたたみコードを示します。

検索と置換

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

Query Editor は検索と置換の機能をサポートしています。

エディタ コントロール

エディタには 3 つのコントロールがあり、クエリをどのように操作するかを指定します。

[MQL Query Editor] コントロール。

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

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

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

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

判読性の改善のためクエリを再フォーマットするには、[FORMAT] をクリックします。クエリを再フォーマットしても、クエリの意味は変更されません。再フォーマットでは、行の長さが 80 文字になります。そのため、クエリエディタのウィンドウがこれより短い場合は、行がラップされます。

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

グラフを保存する

Metrics Explorer から

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

  1. 自動実行オプションを有効にしていない場合は、グラフを保存する前に [Run Query] をクリックしてクエリを実行します。最初にクエリを実行しない場合、クエリエディタは最後に実行したクエリを保存します。

  2. [Save Chart] をクリックします。 ダイアログ ボックスに、グラフを保存するとクエリが厳密な形式に置き換えられるという内容のメッセージが表示されます。詳細については、厳密な形式のクエリをご覧ください。

  3. グラフの保存を続行するには:

    1. グラフにわかりやすいタイトルを付けます。
    2. 新しいグラフを表示する目的のダッシュボードを選択します。
    3. ダイアログで [Save]をクリックします。

ダッシュボードから

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

  1. グラフにわかりやすいタイトルを付けます。

  2. 自動実行オプションを有効にしていない場合は、グラフを保存する前に [Run Query] をクリックしてクエリを実行します。最初にクエリを実行しない場合、クエリエディタは最後に実行したクエリを保存します。

  3. [保存] をクリックします。ダイアログ ボックスに、グラフを保存するとクエリが厳密な形式に置き換えられるという内容のメッセージが表示されます。詳細については、厳密な形式のクエリをご覧ください。

  4. ダイアログで [保存] をクリックしてグラフを保存し、ダッシュボードに戻ります。

Query Editor の終了

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

期間、グラフ、クエリエディタ

アラート ポリシーの条件で使用される MQL クエリを除き、クエリエディタの MQL クエリには期間を含める必要があります。期間には、クエリの一部として返されるデータのサブセットを指定します。

期間は、グラフの時間セレクタを使用して暗黙的に、または MQL クエリテキストで明示的に表すことができます。

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

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

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

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

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

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

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

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

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

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

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

  1. エディタで指定したクエリは、簡潔または厳密な形式に変換されます。変換によってクエリの意味が変更されることはありませんが、完全な列名やアライメント オペレーションなど、クエリで想定されている明示的な処理が行われます。詳細については、厳密な形式のクエリをご覧ください。

  2. クエリの時間範囲の選択が削除されます。ダッシュボードのグラフではタイムセレクタを共有し、そのセレクタへの変更はダッシュボード上のすべてのグラフに適用されます。したがって、元のクエリの期間セレクタは不要になります。

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

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

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

  • within: クエリ出力ウィンドウを指定します。このオペレーションで、返されるデータの量が決まります。たとえば、within 1h を指定すると、タイムスタンプが過去 1 時間以内のポイントのみを生成します。そのため、このオペレーションはグラフのタイムセレクタ オプションをオーバーライドします。

  • 次のオペレーションは、出力テーブルのアラインメント期間に関連しています。どちらも、入力としてアラインメントされたテーブルを要求するか、デフォルトを指定します。

    • every: 整列されたテーブル出力の期間を指定します。

    • window: アライメント操作のウィンドウを指定します。

    どちらの場合も、align オペレーションで明示的なアラインメント ウィンドウが指定された場合、window オペレーションに指定された期間と一致する必要があります。delta アライメント関数の場合、アライメント ウィンドウと期間は同じである必要があります。明示的なアラインメント ウィンドウが指定されている場合、every オペレーションが合意する必要があります。いずれの場合も、アライメント ウィンドウは少なくともアライメント期間と同じ大きさである必要があります。そうでない場合、入力データは無視されます。

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

Monitoring のグラフでは、グラフの期間はグラフの時間範囲セレクタの値に基づいて設定されます。たとえば、1 週間を選択した場合、グラフの期間は 1 時間になります。この値は、チャート領域にあるチップと呼ばれる角が丸い小さなボックスに表示されます。グラフ期間を示すチップには、1 hr interval のようなラベルが付けられます。次のスクリーンショットは、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 Console から MQL ベースのアラート ポリシーを作成するには、アラート ポリシーの管理で説明されているポリシーを作成するための通常の手順に従いますが、アラート ポリシーの条件を作成する場合は、フォームベースの指標セレクタの代わりにクエリエディタを使用します。

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

クエリ コンバージョン

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

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

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

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

指標とモニタリング対象リソースのタイプが手動で入力されています。[Advanced Aggregation] の [Aligner] と [Alignment Period] の値は、デフォルト値です。

[ クエリエディタ] をクリックすると、フォームベースのセレクタのクエリが MQL クエリに変換されます。変換の結果は、次のスクリーンショットのようになります。

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

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