Logging のクエリ言語を使用したクエリの作成

このドキュメントでは、ログ エクスプローラを使用するときにログを取得して分析する方法について説明します。クエリを作成して実行し、ログを取得します。クエリを作成するには、フィルタ メニューから選択し、ログエントリに含まれるオプションを使用して、クエリエディタ フィールドを使用します。ビルドするクエリは、Logging クエリ言語で記述されます。

始める前に

  • クエリを作成するには、ログデータを読み取る権限が必要です。これらの権限は、ログビューアのロール（roles/logging.viewer）に含まれます。必要な IAM 権限の詳細については、Google Cloud コンソールの権限をご覧ください。

  • クエリを共有するには、Identity and Access Management ロールに logging.queries.share 権限が含まれている必要があります。この権限は、オーナー（roles/owner）のロールとロギング管理者（roles/logging.admin）のロールに含まれています。

    各 Logging ロールに関連付けられている権限のリストについては、Logging のロールをご覧ください。

クエリを作成する

Google Cloud コンソールを使用してクエリを作成する手順は次のとおりです。

  1. Google Cloud コンソールで [ロギング] を選択し、[ログ エクスプローラ] を選択するか、次のボタンをクリックします。

    ログ エクスプローラに移動

  2. ログを表示する対象の Google Cloud プロジェクトまたは他の Google Cloud リソースを選択します。

    Amazon Web Services（AWS）アカウントから Logging に送信するログを表示するには、Google Cloud コンソール リソース選択ツールで AWS コネクタ プロジェクトを選択してから、ログ エクスプローラを使用します。AWS コネクタ プロジェクトは、AWS アカウントの Amazon Resource Name（ARN）を保存し、AWS アカウントを Google Cloud サービスにリンクします。詳細については、AWS アカウントから指標を収集するをご覧ください。

  3. [クエリ] ペインを使用してクエリを作成します。

    [ログ エクスプローラ] クエリペイン

    [クエリ] ペインには、クエリ式を作成して実行するための複数の方法が用意されています。

    • すべてのログフィールドのテキストを検索します。
    • フィルタ メニューからオプションを選択します。
    • Query Editor を使用して、クエリを作成または変更します。
    • [最近]、[保存済み]、[推奨]、[ライブラリ] タブでクエリを表示、編集、実行します。

複数のログフィールドでテキストを検索する

すべてのログフィールドでテキストを検索し、一致するすべてのログエントリを見つけるには、検索フィールドに検索キーワードを入力します。

クエリペインにあるログ エクスプローラの検索フィールド。

単語やフレーズを検索できます。検索キーワードには、ブール演算子と正規表現を含めることができます。

  • トークンの境界に沿って大文字と小文字を区別しない検索を実行するには、検索キーワードをバッククォートまたは二重引用符なしで入力します。

    たとえば、単語 hello と単語 world を含むログエントリを検索するには、「hello world」と入力します。SEARCH("hello world") に変換されるこのコマンドは、トークン hello と world を含むログエントリを任意の順序で照合します。検索では大文字と小文字が区別されないため、検索ではトークン Hello と World を含むログエントリとも一致します。この検索ではトークン worlds と一致しません。

  • トークンの境界に従ってフレーズで大文字と小文字が区別されない検索を実行するには、フレーズをバッククォートでラップします。

    たとえば、hello world というフレーズを検索するには、「`hello world`」と入力します。このコマンド（SEARCH("`hello world`") に変換）は、トークン hello world を含むログエントリと一致します。この検索ではトークン hello worlds と一致しません。

  • 部分文字列の検索で大文字と小文字を区別しない場合は、テキストを二重引用符で囲みます。たとえば、"hello world" は Hello World および Hello world と一致します。検索はトークン境界に沿って実行されないため、同じクエリが hello worlds にも一致します。

クエリ式内で検索キーワードを表示するには、[クエリを表示] を有効にします。

検索キーワードを入力したら、[クエリを実行] をクリックするか Enter キーを押します。クエリの結果は [クエリ結果] ペインに表示されます。

ブール演算子

検索フィールド エントリは、選択した Google Cloud リソース内のすべてのログエントリのサブセットを指定するブール式に変換されます。

検索フィールドでは、ブール演算子 AND、OR、NOT を使用できます。検索式でブール演算子を使用する場合は、次の点に注意してください。

  • かっこを使用してルールをネストすることはできません。検索式に含まれる括弧は、検索キーワードとして解析されます。
  • ブール演算子は大文字にする必要があります。小文字の and、or、not は、演算子ではなく検索キーワードとして解析されます。

演算子がない場合は、すべての検索キーワードとフレーズが AND で結合されます。検索キーワード間の AND 演算子は省略できます。

AND 演算子と OR 演算子は短絡評価の演算子です。同じ式の中で AND ルールと OR ルールを組み合わせることができます。たとえば、2 つの演算子が混在している場合、式 a AND b OR c AND d は次の Logging クエリ言語式に変換されます。

"a"
"b" OR "c"
"d"

NOT 演算子の優先順位が最も高く、その後に OR と AND が順に続きます。

NOT 演算子は、後続の用語の否定を実行します。たとえば、NOT error は error を含まないログエントリを返します。また、NOT 演算子の代わりに -（マイナス記号）を使用できます。たとえば、次の 2 つのクエリは同じです。

"response" AND "successful" AND NOT "error"

"response successful" -"error"

-（マイナス）演算子が引用符の外側にある場合も、この論理はフレーズに対して機能します。たとえば、次の 2 つのクエリは同じです。

-"response successful"

NOT "response successful"

フィルタ メニューを使用してクエリを作成する

[クエリ] ペインのフィルタ メニューを使用して、リソース、ログ名、ログ重大度パラメータを Query Editor フィールドに追加できます。これらのオプションは、Logging のすべてのログの LogEntry フィールドに対応します。

[リソース] メニューと [ログ名] メニューのオプションは、現在 Cloud Logging に保存されているログのみを表示します。

クエリエディタのフィルタ メニュー

  • リソース: resource.type と関連する resource.labels を指定できます。このフィルタ メニューを使用して単一のリソースタイプと、クエリに適用する 0 個以上のリソースラベルを選択できます。リソース パラメータは、論理演算子 AND で結合されています。
  • ログ名: logName を指定できます。複数のログ名を選択して、クエリに適用できます。複数のログ名を選択する場合は、論理演算子 OR を使用します。
  • 重大度: 重大度を指定できます。クエリに適用する複数の重大度レベルを同時に選択できます。 複数の重大度を選択する場合は、論理演算子 OR を使用します。

フィルタ メニューを使用するには、次の操作を行います。

  1. [クエリ] ペインにあるフィルタ メニューのいずれかで [メニュー] を開きます。

  2. フィルタ パラメータを絞り込みます。

  3. [適用] をクリックします。Query Editor フィールドにパラメータが表示されます。

    クエリ式内で検索キーワードを表示するには、[クエリを表示] を有効にします。

  4. クエリを確認したら、[クエリを実行] をクリックします。クエリの結果は [クエリ結果] ペインに表示されます。

特定の Compute Engine リソースタイプ（gce_instance や gce_network など）では、サブテキストとしてリソース ID が付いたリソース名が表示されます。たとえば、gce_instance リソースタイプの場合、VM 名と VM ID が並んで表示されます。リソース名は、クエリを作成する正しいリソース ID の識別に役立ちます。

期間単位のログを表示する

特定の期間に書き込まれたログを表示するには、次の 2 つの方法があります。

  1. 期間セレクタを使用する。
  2. Query Editor フィールドにタイムスタンプ式を含める。

期間セレクタを使用する

デフォルトの期間は 1 時間ですが、プリセット時間のオプションから選択したり、カスタムの開始時刻と終了時刻を指定したり、期間セレクタを使用して特定のタイムスタンプの前後の期間を中央に配置したりできます。たとえば、過去 1 週間のデータを表示するには、期間セレクタから [過去 1 週間] を選択します。

期間セレクタを使用してタイムゾーンの設定を行うこともできます。

Query Editor フィールドにタイムスタンプ式を含める

タイムスタンプ式を直接クエリエディタ フィールドに追加するには、Logging クエリ言語を使用します。

Query Editor フィールドにタイムスタンプを含む式がある場合、期間セレクタは無効になり、クエリはタイムスタンプ式を期間の制限として使用します。クエリがタイムスタンプ式を使用しない場合、クエリは時間範囲セレクタを時間範囲の制限として使用します。

Logging のクエリ言語を使用した高度なクエリを記述する

ロギングクエリ言語を使用すると、ログ エクスプローラのクエリエディタ フィールドでさらに高度なクエリを作成できます。

  1. [クエリ] ペインにクエリエディタ フィールドが表示されない場合は、[クエリを表示] を有効にします。

  2. クエリ式を直接クエリ式フィールドに入力します。

    検索フィールドに検索キーワードを追加した場合や、フィルタ メニューでパラメータを選択した場合は、クエリエディタ フィールドにも表示され、クエリ式の一部として評価されます。

  3. クエリを確認したら、[クエリを実行] をクリックします。

    クエリに一致するログが [クエリ結果] ペインの下に表示されます。[ヒストグラム] ペインと [ログフィールド] ペインもクエリ式に従って調整されます。

使用する一般的なクエリの例については、ログ エクスプローラを使用したサンプルクエリをご覧ください。

最近のクエリを使用する

クエリを実行すると、そのクエリは [最近] クエリのリストに追加されます。このリストには、過去 30 日間の上位 10,000 件の一意のクエリが含まれます。

最近のクエリを表示するには、[Query] ペインで [最近] タブを選択します。[最近] タブには、次のオプションが表示されます。

  • ストリーム: クエリを実行して結果をストリーミングするには、このオプションを選択します。
  • 実行: クエリを実行するには、このオプションを選択します。

  • その他のオプション: クエリを実行するか、[保存済み] クエリのリストに保存するかを選べるオプションを指定できるクエリ式が表示されます。クエリを直接選択して、これらのオプションを指定することもできます。

    クエリを保存するには、次の操作を行います。

    1. [名前を付けて保存] をクリックします。 [クエリの保存] ダイアログが開きます。

    2. 次のフィールドに値を入力します。

      • 名前（必須）: クエリの名前を指定します。名前は 64 文字に制限されています。
      • 説明（省略可）: クエリの目的がわかるような説明を入力します。
      • 概要フィールドを含める（省略可）: [概要フィールドを含める] を有効にして、表示する概要フィールドを入力します。
      • [サマリー フィールドを切り捨て]（省略可）: [サマリー フィールドを切り捨て] を有効にして、切り捨てる文字数と切り捨てを実行するかどうかを選択します。

    3. [クエリを保存] をクリックします。 これで、クエリが保存済みクエリリストに表示されるようになりました。

最近のクエリを並べ替えることもフィルタリングすることもできます。フィルタはクエリ式内のテキストと一致します。

クエリを保存する

[Query] ペインには [保存済み] タブがあり、このタブから保存したクエリにアクセスできます。 保存したクエリを使用すると、クエリの式を保存し、より一貫性のある効率的な方法でログを分析できます。

Query Editor フィールドで作成したクエリ式を保存するには、次の操作を行います。

  1. [Query] ペインで [保存] をクリックします。[クエリを保存] ダイアログが開き、クエリ式が [クエリエディタ] フィールドに表示されます。

  2. 次のフィールドに値を入力します。

    • 名前（必須）: クエリの名前を指定します。名前は 64 文字に制限されています。
    • 説明（省略可）: クエリの目的がわかるような説明を入力します。
    • 概要フィールドを含める（省略可）: [概要フィールドを含める] を有効にして、表示する概要フィールドを入力します。
    • [サマリー フィールドを切り捨て]（省略可）: [サマリー フィールドを切り捨て] を有効にして、切り捨てる文字数と切り捨てを実行するかどうかを選択します。
    1. [クエリを保存] をクリックします。 保存したクエリは、[保存済み] タブに一覧表示されます。

保存したクエリを実行するには、[実行] をクリックします。クエリを実行して結果をストリーミングするには、[ストリーム] をクリックします。

保存したクエリを並べ替えることもフィルタリングすることもできます。フィルタはクエリ式内のテキストと一致します。

クエリを共有する

共有クエリを使用すると、Google Cloud プロジェクトのユーザーが、保存したクエリを互いに共有できます。共有クエリは、[保存済み] タブで表示できます。

共有クエリの表示と編集に必要なロールと権限については、Google Cloud コンソールの権限をご覧ください。 なお、IAM ロール roles/logging.admin または roles/editor を持つユーザーは、他のユーザーの共有クエリを編集できます。

共有クエリを作成する

すでに保存したクエリを共有することも、新しいクエリを共有することもできます。

クエリを作成して共有する方法は次のとおりです。

  1. Query Editor フィールドにクエリを入力します。

  2. [保存] をクリックします。

  3. [クエリの保存] ダイアログのフィールドに値を入力します。

  4. [Share with project] を有効にします。

  5. [クエリを保存] をクリックします。

クエリが Google Cloud プロジェクトの他のユーザーと共有されるようになりました。

すでに保存したクエリを共有するには、次の操作を行います。

  1. [保存済み] タブを選択します。

  2. [その他のオプション] を選択して、 [編集] を選択するか、クエリを直接選択します。

  3. [クエリを編集] ダイアログで、[Share with project] を有効にして、[クエリを更新] を選択します。

クエリが Google Cloud プロジェクトの他のユーザーと共有されるようになりました。

共有クエリを表示

すべての共有クエリをすばやく表示するには、[公開設定] 列を並べ替えて共有クエリを最初に表示します。

  1. [保存済み] タブを選択します。

  2. [すべて] をクリックします。

  3. [公開設定] 列を並べ替えます。

[公開設定] 列は、クエリの共有有無および共有方法を表します。

  • 共有したアイテム: 自分が保存して、Google Cloud プロジェクトの他のユーザーと共有したクエリ。
  • 共有: Google Cloud プロジェクトの他のユーザーが共有したクエリ。
  • 非公開: 自分が保存して、Google Cloud プロジェクトの他のユーザーと共有しなかったクエリ。

クエリのみを表示する

作成または共有した保存済みクエリを表示するには、[Mine] をクリックします。作成して保存したクエリのリストが表示されます。[公開設定] 列で、共有されていない非公開クエリを確認できます。共有したクエリは [共有者] で示されます。

推奨クエリを使用する

Logging は、Google Cloud プロジェクトのコンテキスト（使用している Google Cloud プロダクトなど）に基づいて、推奨クエリを生成します。推奨クエリを使用することで、問題を特定することや、システム全体の健全性に関する分析情報を得ることができます。たとえば、Google Kubernetes Engine の使用を検出すると、Logging はコンテナのすべてのエラーログを検索するクエリを提案することがあります。

推奨クエリを表示して実行するには、[クエリ] ペインで [推奨] タブを選択します。[推奨] タブには、クエリのリストとともに、説明と次のオプションが表示されます。

  • ストリーム: クエリを実行して結果をストリーミングするには、このオプションを選択します。
  • 実行: クエリを実行するには、このオプションを選択します。

  • その他のオプション: クエリを実行するか、保存するかを選べるオプションを指定できるクエリ式の詳細が表示されます。クエリを直接選択して、これらのオプションを指定することもできます。

    推奨クエリの詳細を確認するには、次のいずれかを行います。

    • クエリの行を選択します。

    • [ その他] をクリックして、[表示] を選択します。[クエリの詳細] ダイアログが開きます。

    [クエリの詳細] ダイアログにクエリと、実行、ストリームまたは名前を付けて保存のオプションが表示されます。

    • クエリを保存するには、次の操作を行います。

      1. [名前を付けて保存] をクリックします。
      2. [クエリの保存] ダイアログのフィールドに値を入力します。

      編集したクエリが [保存済み] のリストに表示されます。このリストでは、後でクエリを実行することもできます。

    • クエリを実行するには、[実行] をクリックします。クエリが実行され、クエリエディタ フィールドに表示されます。

    • クエリを今すぐ実行して結果をストリーミングするには、[ストリーム] をクリックします。

    • ダイアログを閉じて推奨クエリのリストに戻るには、[閉じる] をクリックします。

次の想定される動作に注意してください。

  • ページを続けて読み込んだ際、同じクエリが同じ順序で表示されない場合があります。
  • 推奨クエリが表示されないことがあります。
  • 推奨クエリを実行しても、ログが返されないことがあります。

ライブラリからクエリを選択する

Logging は、一般的なユースケースと Google Cloud プロダクトに基づくクエリのライブラリを提供します。これらのクエリは、時間的制約のあるトラブルシューティング セッションでログを効率的に検索し、利用可能なログデータを詳しく把握するためにログを調べることができます。

ライブラリのクエリを表示して実行する方法は次のとおりです。

  1. [クエリ] ペインで [ライブラリ] タブを選択します。

  2. [すべてのクエリ] 列には、利用可能なカテゴリと Google Cloud プロダクトに基づくクエリのサブセットが表示されます。表示されるクエリを絞り込むには、いずれかのプロダクトをクリックします。

    検索フィールドを使用して、利用可能なクエリをカテゴリ、説明、クエリ式の内容で検索することもできます。

  3. クエリ式を確認するには、次のいずれかを行います。

    a. クエリの行をクリックします。

    b. [ その他] をクリックして、[表示] を選択します。

  4. [クエリの詳細] ダイアログに、クエリと、[実行]、[ストリーム]、[名前を付けて保存] のオプションが表示されます。

    • クエリを保存するには、次の操作を行います。

      1. [名前を付けて保存] をクリックします。
      2. [クエリの保存] ダイアログのフィールドに値を入力します。

      編集したクエリが [保存済み] のリストに表示されます。このリストでは、後でクエリを実行することもできます。

    • クエリを実行するには、[実行] をクリックします。クエリが実行され、クエリエディタ フィールドに表示されます。

    • クエリを今すぐ実行して結果をストリーミングするには、[ストリーム] をクリックします。

    • ダイアログを閉じて推奨クエリリストに戻るには、[閉じる] をクリックします。

次のステップ