Logging のクエリ言語を使用してクエリを作成して保存する

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

クエリは、ログ エクスプローラ ページで保存することも、Logging API メソッド savedQueries.create を使用して保存することもできます。

始める前に

• ログデータを読み取ってクエリを作成したり、非公開の保存したクエリを使用したり、共有クエリを一覧表示して取得したりするために必要な権限を取得するには、プロジェクトに対するログビューア （roles/logging.viewer）の IAM ロールを付与するよう管理者に依頼してください。

  この事前定義ロールには、ログデータを読み取ってクエリを作成したり、非公開の保存済みクエリを使用したり、共有クエリを一覧表示して取得したりするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

  必要な権限

  ログデータを読み取ってクエリを作成したり、非公開の保存したクエリを使用したり、共有クエリを一覧表示して取得したりするには、次の権限が必要です。

  • 非公開の保存したクエリを使用する: logging.queries.usePrivate
  • 共有クエリを一覧表示して取得する:
    • logging.queries.listShared
    • logging.queries.getShared

• 共有クエリの作成、更新、削除を行うために必要な権限を取得するには、プロジェクトに対する Logging 管理者（roles/logging.admin）の IAM ロールを付与するよう管理者に依頼してください。

  この事前定義ロールには、共有クエリの作成、更新、削除を行うために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

  必要な権限

  共有クエリの作成、更新、削除を行うには、次の権限が必要です。

  • logging.queries.share
  • logging.queries.updateShared
  • logging.queries.deleteShared

必要な IAM 権限の詳細については、Google Cloud コンソールの権限をご覧ください。

クエリを作成する

Google Cloud コンソールを使用してクエリを作成するには、次の操作を行います。

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

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

   検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

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

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

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

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

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

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

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

• 大文字と小文字を区別して検索するには、正規表現を使用する必要があります。

• トークンの境界で大文字と小文字を区別しない検索を行うには、バッククォートまたは二重引用符を使用せずに検索語を入力します。

  たとえば、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 にも一致します。

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

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

ブール演算子

検索フィールドのエントリは、選択した 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"

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

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

[リソース] メニューと [ログ名] メニューのオプションは、Cloud Logging によって保存されるログエントリから取得されます。

• リソース: resource.type と関連付けられた resource.labels を指定できます。このフィルタ メニューと、クエリに適用する 0 個以上のリソースラベルを使用して、単一のリソースタイプを選択できます。リソース パラメータは論理演算子 AND で結合されます。
• ログ名: logName を指定できます。クエリに適用するログ名を複数選択できます。複数のログ名を選択する場合は、論理演算子 OR を使用します。
• 重大度: 重大度を指定できます。クエリに適用するために追加する複数の重大度レベルを同時に選択できます。 複数の重大度を選択する場合は、論理演算子 OR を使用します。
• 関連付け: ログエントリをグループ化して「親子」形式で表示できます。詳細については、ログエントリを関連付けるをご覧ください。

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

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

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. クエリを確認したら、[クエリを実行] をクリックします。

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

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

最近のクエリを使用する

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

最近のクエリを表示するには、メインツールバーの menu_book [クエリ ライブラリ] ボタンを選択します。最近のクエリには、次のオプションがあります。

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

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

  クエリを保存する手順は次のとおりです。

  1. [保存] をクリックします。[クエリを保存] ダイアログが開きます。

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

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

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

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

クエリの保存と共有

保存したクエリを使用すると、クエリの式を保存し、より一貫性のある効率的な方法でログを分析できます。 ログ エクスプローラにはクエリ ライブラリがあり、保存したクエリにアクセスできます。Logging API メソッド savedQueries.create を使用してクエリを保存することもできます。

クエリを保存して非公開にし、自分にのみ表示できるようにすることも、Google Cloud プロジェクトの他のメンバーと共有することもできます。クエリを共有すると、そのクエリはユーザーの所有権から外れ、必要な権限を持つプロジェクト内のすべてのメンバーがクエリにアクセスできるようになります。

{
  "parent": "projects/my-project/locations/global"
  "savedQueryId": "compute-query"
  {
    "displayName": "compute-admin-activity-query",
    "description": "Queries for Compute Engine Admin Activity logs.",

    "loggingQuery":
      {
        "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
      },
    "visibility": "PRIVATE"
  }
}

保存したクエリを表示

menu_book [クエリ ライブラリ] ボタンをクリックすると、非公開クエリと Google Cloud プロジェクト内の他のメンバーと共有されているクエリの両方を表示できます。

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

推奨クエリを使用する

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

推奨クエリを表示して実行するには、menu_book [クエリ ライブラリ] ボタンをクリックし、[推奨] をクリックします。[推奨] タブには、次のオプションが表示されます。

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

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

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

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

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

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

  • クエリを保存する手順は次のとおりです。

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

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

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

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

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

次の動作が想定されます。

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

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

Logging には、一般的なユースケースと Google Cloud プロダクトに基づくクエリのライブラリが用意されています。これらのクエリを使用すると、時間のかかるトラブルシューティング セッション中にログを効率的に見つけ、ログを調べて利用可能な Logging データを把握できます。

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

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

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

   検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

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

3. menu_book [ライブラリをクエリ] ボタンをクリックします。使用可能なクエリのカテゴリと、Google Cloud プロダクトに基づくクエリのサブセットが表示されます。表示されるクエリの選択を絞り込むには、いずれかの製品をクリックします。

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

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

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

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

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

   • クエリを保存する手順は次のとおりです。

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

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

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

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

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

次のステップ

• サンプルクエリ