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

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

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

準備

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

• クエリを保存するには、Identity and Access Management ロールに logging.queries.{list, create, get, update, delete} 権限が含まれている必要があります。

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

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

クエリを作成する

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

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

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

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

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

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

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

   

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

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

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

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

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

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

  たとえば、単語 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"

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

[クエリ] ペインのフィルタ メニューを使用して、リソース、ログ名、ログの重大度のパラメータを [クエリエディタ] フィールドに追加できます。こうしたオプションは、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. クエリ式を直接クエリ式フィールドに入力します。

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

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

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

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

注: クエリの長さは 20,000 文字以下にする必要があります。

最近のクエリを使用する

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

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

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

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

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

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

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

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

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

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

クエリを保存する

注: データが Assured Workloads 環境を介して管理されている場合は、この機能が影響を受けることや、制限される可能性があります。詳細については、Assured Workloads の制限と上限をご覧ください。

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

コンソール

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

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

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

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

3. [クエリを保存] をクリックします。 保存したクエリは、[保存済み] タブのリストに表示されます。

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

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

API

Logging API を使用してクエリを保存するには、savedQueries.create メソッドを使用します。このメソッド、そのパラメータ、レスポンス データの詳細については、savedQueries.create のリファレンス ページをご覧ください。

savedQueries.create　メソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。 ログ エクスプローラ クエリでは、loggingQuery フィールドを指定する必要があります。次の例は、SavedQuery のインスタンスを含むサンプル リクエスト本文を示しています。

{
"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"
}
}

クエリを共有する

共有クエリを使用すると、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 プロジェクトの他のユーザーと共有されるようになりました。

API

Logging API で共有クエリを作成するには、savedQueries.Create メソッドを使用し、visibility フィールドに SHARED の値を指定します。

共有クエリを表示

コンソール

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

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

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

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

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

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

クエリのみを表示する

作成または共有したクエリを表示するには、[Mine] をクリックします。作成して保存したクエリのリストが表示されます。[公開設定] 列には、共有されていない [非公開] クエリが表示されます。共有しているクエリは、[共有アイテム] として表示されます。

推奨クエリを使用する

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Logging は、一般的なユースケースと Google Cloud プロダクトに基づくクエリのライブラリを提供します。これらのクエリは、時間的制約のあるトラブルシューティング セッション中にログを効率的に検索し、ログを調べて利用可能なロギングデータについて理解を深めるのに役立ちます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

次のステップ

• サンプルクエリ