Logging のクエリ言語を使用してクエリを作成して保存する
コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

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

作成したクエリは、[ログエクスプローラ] ページまたは Logging API メソッド savedQueries.create で保存できます。

始める前に

ログ閲覧者ロール（roles/logging.viewer）は、ログを表示するためのアクセス権を付与します。このロールが付与されている場合、クエリを作成して実行できます。クエリを非公開クエリとして保存し、非公開クエリと共有クエリの両方を実行できます。ただし、このロールでは共有クエリの保存や変更はできません。共有クエリを保存または変更する場合は、Cloud Logging に対する完全アクセスが許可されるロギング管理者ロール（roles/logging.admin）が付与されていることを確認してください。

次のいずれかを行います。

クエリの作成と実行、非公開クエリの実行と保存、共有クエリの実行に必要な権限を取得するには、プロジェクトに対するログ閲覧者（roles/logging.viewer）IAM ロールを付与するよう管理者に依頼してください。

クエリの作成と実行、非公開クエリの実行と保存、共有クエリの実行、作成、管理に必要な権限を取得するには、プロジェクトに対するロギング管理者（roles/logging.admin）IAM ロールを付与するよう管理者に依頼してください。

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

クエリを作成する

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

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

このページを検索バーで検索する場合は、小見出しが「Logging」の結果を選択します。
ログを表示する Google Cloud プロジェクトまたはその他の Google Cloudリソースを選択します。
[クエリ] ペインでクエリを作成します。

[クエリ] ペインでは、いくつかの方法でクエリ式を作成して実行できます。
- すべてのログフィールドのテキストを検索します。
- フィルタメニューからオプションを選択します。
- クエリエディタでクエリの作成または変更を行います。
- クエリライブラリで、保存済みクエリ、最近のクエリ、推奨クエリを表示して実行します。

すべてのログフィールドのテキストを検索する

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

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

大文字と小文字を区別して検索するには、正規表現を使用します。
トークンの境界に沿って大文字と小文字を区別せずに検索するには、バッククォートまたは二重引用符で囲まずに検索語句を入力します。

たとえば、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 を使用します。
関連付け: ログエントリをグループ化して「親子」形式で表示できます。詳細については、ログエントリを関連付けるをご覧ください。

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

[クエリ] ペインにあるフィルタメニューのいずれかで（メニュー）を開きます。
フィルタパラメータを絞り込みます。
[適用] をクリックします。クエリエディタフィールドにパラメータが表示されます。

クエリ式内で検索キーワードを表示するには、[クエリを表示] を有効にします。
クエリを確認したら、[クエリを実行] をクリックします。[クエリ結果] ペインにクエリの結果が表示されます。

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

特定の期間のログを表示する

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

期間セレクタを使用する。
クエリエディタフィールドにタイムスタンプ式を含める。

期間セレクタを使用する

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

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

クエリエディタフィールドにタイムスタンプ式を含める

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

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

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

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

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

検索フィールドに検索語句を追加した場合や、フィルタメニューでパラメータを選択した場合、これらもクエリエディタフィールドに表示され、クエリ式の一部として評価されます。
クエリを確認したら、[クエリを実行] をクリックします。

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

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

最近のクエリを使用する

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

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

ストリーム: クエリを実行して結果をストリーミングするには、このオプションを選択します。
実行: クエリを実行するには、このオプションを選択します。
その他のオプション: クエリ式とオプション（クエリを実行するか、保存済みクエリのリストに保存するか）が表示されます。クエリを直接選択して、これらのオプションを指定することもできます。

クエリを保存するには、次の操作を行います。
1. [保存] をクリックします。[クエリを保存] ダイアログが開きます。
2. 次のフィールドに値を入力します。
  - 名前（必須）: クエリの名前を入力します。名前は 64 文字以下にする必要があります。
  - 説明（省略可）: クエリの目的がわかるような説明を入力します。
  - 概要フィールドを含める（省略可）: [概要フィールドを含める] を有効にして、表示する概要フィールドを入力します。
  - [概要フィールドを切り詰める]（省略可）: [概要フィールドを切り詰める] を有効にして、切り捨てる文字数と切り捨てを行うかどうかを選択します。
3. [クエリを保存] をクリックします。これで、クエリが保存済みクエリのリストに表示されるようになりました。

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

クエリを保存して共有する

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

クエリを保存して非公開にし、自分だけが閲覧できるようにすることも、 Google Cloud プロジェクトの他のメンバーと共有することもできます。クエリを共有すると、そのクエリの所有者ではなくなります。プロジェクトで必要な権限を持つのすべてのメンバーがクエリにアクセスできるようになります。

コンソール

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

[クエリ] ペインで [保存] をクリックします。[クエリを保存] ダイアログが表示され、クエリ式がクエリエディタフィールドに表示されます。
次のフィールドに値を入力します。
- 名前（必須）: クエリの名前を入力します。名前は 64 文字以下にする必要があります。
- 説明（省略可）: クエリの目的がわかるような説明を入力します。
- カスタム概要フィールドを含める（省略可）: [概要フィールドを含める] を有効にして、表示する概要フィールドを入力します。
- [概要フィールドを切り詰める]（省略可）: [概要フィールドを切り詰める] を有効にして、切り捨てる文字数と切り捨てを行うかどうかを選択します。
- プロジェクトと共有する: 必要に応じて、[プロジェクトと共有する] を有効にして、 Google Cloud プロジェクトの他のメンバーとクエリを共有します。
[クエリを保存] をクリックします。保存したクエリは、[保存済み] タブのリストに表示されます。

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

保存したクエリを変更するには、（その他のオプション）、[ 編集] の順に選択します。クエリを選択して変更を行い、変更したクエリを保存することもできます。

保存したクエリを削除するには、（その他のオプション）、[ 削除] の順に選択します。

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

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 プロジェクトの他のメンバーとクエリを共有するには、visibility フィールドに SHARED の値を指定します。

保存したクエリを表示する

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

コンソール

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

このページを検索バーで検索する場合は、小見出しが「Logging」の結果を選択します。
ログを表示する Google Cloud プロジェクトまたはその他の Google Cloudリソースを選択します。
[ クエリライブラリ] ボタンをクリックして、[保存済み] をクリックします。

表は見出しで並べ替えることができます。[公開設定] 列は、クエリが共有されているか、非公開かを示します。

共有:Google Cloud プロジェクトの他のメンバーと共有されているクエリ。
非公開: クエリを保存したユーザーにだけ表示されます。

API

Logging API を使用して、savedQueries.list メソッドで非公開クエリと共有クエリを表示できます。

たとえば、次のリクエスト本文は、ワイルドカードのロケーション ID を含むすべての共有ログエクスプローラクエリの一覧を取得します。

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

推奨クエリを使用する

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

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

ストリーム: クエリを実行して結果をストリーミングするには、このオプションを選択します。
実行: クエリを実行するには、このオプションを選択します。
その他のオプション: クエリ式の詳細とオプション（クエリを実行するか、保存するか）が表示されます。クエリを直接選択して、これらのオプションを指定することもできます。

推奨クエリの詳細を確認するには、次のいずれかを行います。
- クエリの行を選択します。
- （その他）をクリックして、[表示] を選択します。[クエリの詳細] ダイアログが開きます。
[クエリの詳細] ダイアログにクエリと、[実行]、[ストリーム] または [名前を付けて保存] のオプションが表示されます。
- クエリを保存するには、次の操作を行います。
  1. [クエリを保存] をクリックします。
  2. [クエリの保存] ダイアログのフィールドに値を入力します。
  編集したクエリは [保存済み] リストに表示され、後でクエリを実行できます。
- クエリをすぐに実行するには、[実行] をクリックします。クエリが実行され、クエリエディタフィールドに表示されます。
- クエリを今すぐ実行して結果をストリーミングするには、[ストリーム] をクリックします。
- ダイアログを閉じて推奨クエリのリストに戻るには、[閉じる] をクリックします。

以下のことは想定内の動作です。

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

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

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

ライブラリのクエリを表示して実行するには、次の操作を行います。

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

このページを検索バーで検索する場合は、小見出しが「Logging」の結果を選択します。
ログを表示する Google Cloud プロジェクトまたはその他の Google Cloudリソースを選択します。
[ クエリライブラリ] ボタンをクリックします。使用可能なクエリのカテゴリと、 Google Cloudプロダクトに基づくクエリのサブセットが表示されます。表示されるクエリの選択肢を絞り込むには、いずれかのプロダクトをクリックします。

検索フィールドを使用して、利用可能なクエリをカテゴリ、説明、クエリ式の内容で検索することもできます。
クエリ式を確認するには、次のいずれかを行います。

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

b. （その他）をクリックして、[表示] を選択します。
[クエリの詳細] ダイアログにクエリと、[実行]、[ストリーム] または [名前を付けて保存] のオプションが表示されます。
- クエリを保存するには、次の操作を行います。
  1. [クエリを保存] をクリックします。
  2. [クエリの保存] ダイアログのフィールドに値を入力します。
  編集したクエリは [保存済み] リストに表示され、後でクエリを実行できます。
- クエリをすぐに実行するには、[実行] をクリックします。クエリが実行され、クエリエディタフィールドに表示されます。
- クエリを今すぐ実行して結果をストリーミングするには、[ストリーム] をクリックします。
- ダイアログを閉じて推奨クエリのリストに戻るには、[閉じる] をクリックします。

次のステップ

サンプルクエリ

Logging のクエリ言語を使用してクエリを作成して保存する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

クエリを作成する

すべてのログフィールドのテキストを検索する

ブール演算子

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

特定の期間のログを表示する

期間セレクタを使用する

クエリエディタ フィールドにタイムスタンプ式を含める

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

最近のクエリを使用する

クエリを保存して共有する

コンソール

API

保存したクエリを表示する

コンソール

API

推奨クエリを使用する

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

次のステップ

Logging のクエリ言語を使用してクエリを作成して保存する
コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

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

クエリエディタフィールドにタイムスタンプ式を含める