ログクエリの作成

このページでは、Google Cloud Console のログビューア(プレビュー版)を使用してログの取得、絞り込み、分析を行い、クエリを作成する方法について説明します。

始める前に

Amazon Web Services(AWS)から Logging にログを送信する場合を除き、Logging を使用するためにワークスペースは必要ありません。

ログビューアには、単一の Google Cloud プロジェクトのログが表示されます。ワークスペースを使用する場合、複数のモニタリング対象プロジェクトにまたがったログの結合は行われません。ログを表示するプロジェクトを選択する必要があります。

ワークスペースと AWS を使用する場合は、AWS コネクタ プロジェクトを選択して AWS ログを表示します。

始めに

ログビューア(プレビュー版)に移動するには、以下の手順に従います。

  1. Google Cloud のナビゲーション メニュー に移動し、[Logging] > [ログビューア] を選択します。
    ログビューアに移動
  2. Google Cloud プロジェクトを選択します。
  3. バージョン選択ツールのメニューから、ログビューアのバージョンを従来版から新しいログビューアのプレビュー版に切り替えます。

ログビューア(プレビュー版)が表示されます。

クエリの作成

クエリビルダー ペインには、ログを取得する複数の方法があります。

  1. クエリビルダーのプルダウン メニュー
  2. クエリビルダーの言語を使用したクエリ
  3. [保存済み] クエリタブ
  4. [最近] クエリタブ

query-builder-pane

以下のセクションでは、クエリを作成、実行してログを取得する方法について説明します。

クエリビルダーのプルダウン メニュー

プルダウン メニューを使用して、クエリビルダーにクエリ パラメータを追加できます。プルダウン メニューを使用して、リソース、ログ名、ログの重大度、期間を選択できます。こうしたオプションは、Google Cloud のすべてのオペレーション スイートのログの LogEntry フィールドに対応しています。

クエリビルダーのプルダウン メニュー

  • リソース: resource.type を指定できます。クエリビルダーに追加するリソースは、一度に 1 つ選択できます。エントリには、論理演算子 AND を使用します。
  • ログ名: logName を指定できます。クエリビルダーに追加するログ名は、一度に複数選択できます。複数のエントリを選択する場合は、論理演算子 OR を使用します。
  • 重大度: 重大度を指定できます。クエリビルダーに追加する重大度は、一度に複数選択できます。複数のエントリを選択する場合は、論理演算子 OR を使用します。

検索パラメータ メニューを使用するには、メニューを展開し、単一のパラメータまたは複数のパラメータを選択し、[追加] をクリックします。

クエリを作成したら、[クエリを実行] をクリックして目的のログエントリを取得します。

時間制限のあるクエリ

時間に基づいてログをクエリする方法は 2 つあります。

  1. タイムスタンプ式を使用したクエリ
  2. 時間範囲セレクタを使用したクエリ

    ログビューア セクションは、時間によるフィルタで、2 つの方法で表示されます。

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

クエリビルダーの言語を使用したクエリ

クエリビルダーの言語を使用して、Cloud Logging クエリビルダー ペイン、Logging APIコマンドライン インターフェースでクエリを作成できます。

詳細については、クエリビルダーの言語をご覧ください。

以下で、クエリを最適化する方法をいくつかご提案します。

クエリを最適化する

ログエントリを効率的に検索する方法は次のとおりです。

  • インデックス フィールドを使用して検索する。
  • 検索対象のログエントリの数を最小限に抑える。

インデックス フィールドの使用

インデックスを活用するには、等価演算子を使用してインデックス フィールドに正確な値を指定します。部分文字列の一致は使用しないでください。

次の LogEntry フィールドがインデックス化されています。

次のセクションでは、これらのインデックス フィールドを使用して、クエリ対象のログエントリの数を最小限に抑える方法について説明します。

ログエントリをすばやく検索する

検索対象のログの数、ログエントリの数、または期間を減らすと、検索が速くなります。3 つすべてを少なくするとさらに速くなります。

例: 正しいログ名を使用する

目的のログエントリがあるログを指定します。いずれかのログエントリを調べて、実際のログ名を確認してください。たとえば、ログビューアの [Compute Engine] セクションに activity_log というログがあります。アクティビティ ログのエントリをよく調べると、実際のログの名前は compute.googleapis.com/activity_log となっています。

次の比較は誤りです。ログ名が誤っているため、何も一致しません。

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

次の比較は正しい比較です。この比較ではアクティビティ ログのログエントリが選択されます。ログ名は次のように URL エンコードする必要があります。

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

例: 正しいログエントリを選択する

目的のログエントリが特定の VM インスタンスからのものであることが判明している場合は、これを指定します。検索対象のログエントリのいずれかを調べて、正しいラベル名を確認します。次の例では、instance_id はインデックス付きラベルの 1 つです。

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

リソースタイプの値を指定する必要があります。そうしなければ、instance_id の比較でインデックスが使用されません。

例: 正しい期間を選択する

検索対象の期間を指定する必要があります。RFC 3339 形式で便利なタイムスタンプを特定するには、GNU/Linux の date コマンドを使用すると簡単です。

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

これらのタイムスタンプの値を次のクエリで使用します。Logging で使用可能なタイムスタンプを作成する場合は、日付と時刻の間の空白を文字 T に置き換えます。

たとえば、直近 3 時間以内を検索するには、次のようにします。

    timestamp >= "2016-06-27T14:40:00-04:00"

直近 5 時間前から 3 時間前までの範囲を検索するには、次のようにします。

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

タイムスタンプを使用する別の例については、このページの一時的なフィールド インデックスをご覧ください。

グローバル検索と部分文字列検索の最小化

ロギングクエリの入力時は近道をしようとしないでください。

例: インデックス フィールドで部分文字列を使用しない

Apache2 ウェブサーバーでログエントリを検索しようとしています。Apache ログの名前は apache-accessapache-error であることがわかっています。この場合の対応について説明します。

  • 入力を減らすために部分文字列一致を使用することは避けてください。

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • インデックス フィールドを検索する場合は、必ず完全一致を使用してください。

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

部分文字列検索を行うと、インデックス フィールドの迅速性が完全に失われます。

例: グローバル検索を使用しない

ペイロードに「Hello, Kitty」という文字列があるログエントリを検索する場合について説明します。

  • グローバル検索は使用しないでください。理由のひとつとして、それらはすべて部分文字列検索であるためです。

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • 検索対象は必ず 1 つのフィールドに限定するようにしてください。これは部分文字列検索を継続する場合も同様です。

        textPayload:"Hello, Kitty"
    
  • 可能であれば、等式テストを実行するようにしてください。

        textPayload = "Hello, Kitty"
    
  • ログエントリに構造化ペイロードがある場合は、ペイロードの各フィールドを参照するようにしてください。

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • インデックス フィールドで検索範囲を制限するようにしてください。

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

検索例

表示されるログエントリは、検索クエリボックス内のクエリに一致するエントリです。[日付を選択] メニューに値がある場合には、画面をスクロールして、その日付まで移動できます。次に例を示します。

resource.type=gae_app

リソースログ メニューから [GAE アプリケーション(すべてのモジュール ID)] を選択し、ログ名メニューから [すべてのログ] を選択した場合、基本クエリ インターフェースと同じログエントリが検索されて表示されます。リソースタイプの一覧については、モニタリング対象リソース一覧をご覧ください。

入力時、ログビューアに完全なフィールド名の候補(例: resource.type)が示されます。

resource.type=gae_app AND logName:request_log

request_log を含むログ名から、App Engine アプリのログエントリを検索します。注意事項:

  • = 演算子は完全に同じであることを意味します。リソースタイプは "gae_app" でなければなりませんが、大文字と小文字は区別されません。
  • : 演算子は "has" を意味します。つまり、logName フィールドに request_log が含まれていなければなりません。ただし、大文字と小文字は区別されません。実際のログ名はずっと長いため、: を使用すると検索に時間がかかる場合があります。
  • この 2 つの比較は AND で結合されています。OR を使用することもできますが、何も指定しない場合は AND であるとみなされます。
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

リソースタイプが Compute Engine VM インスタンスまたは AWS EC2 VM インスタンスのいずれかであるログエントリを検索します。ログエントリの severity が少なくとも ERROR であることが必要です。これは、基本クエリ インターフェースの重大度メニューで [ERROR] を選択することと同じです。基本クエリ インターフェースでは、複数のリソースタイプのログを表示することはできません。

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

プロジェクト [PROJECT_ID] から、管理アクティビティの監査ログエントリをすべて検索します。すべての監査ログがプロジェクト内で同じログ名を使用しますが、リソースタイプは異なります。ログ ID の cloudaudit.googleapis.com/activity は、ログ名で URL エンコードされている必要があります。比較に等価演算子を使用すると検索をスピードアップできます。詳細については、監査ログについてをご覧ください。

unicorn

unicorn を含むログエントリを任意のフィールドから検索します。大文字と小文字は区別しません。フィールド比較に含まれない検索語は、「すべてのフィールド」クエリです。

unicorn phoenix

一部のフィールドに unicorn が含まれていて、かつ、一部のフィールドに phoenix が含まれているログエントリを検索します。

textPayload:(unicorn phoenix)

順序は関係なく、textPayload フィールドに unicornphoenix の両方が含まれているログエントリを検索します。2 つのキーワードは暗黙に AND で結合されます。

textPayload:"unicorn phoenix"

textPayload フィールドに文字列 "unicorn phoenix" を含むログエントリを検索します。これは基本クエリ インターフェースと同じです。

NOT textPayload: "unicorn phoenix"

textPayload フィールドに文字列 "unicorn phoenix" を含まないログエントリを検索します。このタイプのクエリは、不要なログエントリを減らします。

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

30 分間のログエントリを検索します。

保存したクエリ

クエリビルダー ペインには [保存済み] タブがあり、このタブから保存したクエリにアクセスできます。

保存したクエリの一覧

保存したクエリを使用すると、クエリの式を保存し、より一貫性のある効率的な方法でログを分析できます。

クエリビルダー ペインで作成したクエリを保存するには、次の操作を行います。

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

  2. クエリの [名前] を追加します。

    名前は 64 文字に制限されています。

  3. (省略可)クエリに概要フィールドを追加するには、[概要フィールドを含める] をオンにします。

  4. (省略可)クエリの [説明] を追加します。

    説明は 1,000 文字に制限されています。機密情報を含めないでください。

  5. ダイアログで [クエリを保存] をクリックします。

保存したクエリは、クエリビルダー ペインの [保存済み] タブに一覧表示されます。

保存したクエリを実行するには、[クエリを実行] をクリックします。

最近のクエリ

クエリビルダーのペインには、[最近] タブがあります。クエリを実行すると、そのクエリは [最近の] クエリリストに追加されます。このリストには、過去 30 日間の上位 10,000 件の一意のクエリが含まれます。

[最近] タブには、最近のクエリが表示されます。

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

  • 実行. クエリを実行します。
  • その他のオプションクエリ オプションを表示し、クエリを実行するか、保存済みクエリのリストに保存します。クエリを直接選択して、これらのオプションを取得することもできます。

    クエリを実行するには、[実行] を選択します。

    クエリを保存するには、[名前を付けて保存] を選択して次のフィールドに入力します。

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

    [クエリを保存] を選択します。これで、クエリは保存したクエリのリストから利用できます。

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

推奨クエリ

Logging は、使用している Google Cloud サービスの認識に基づいて、推奨クエリを生成します。問題を特定して、システム全体の健全性について分析できるクエリを提案します。たとえば、Google Kubernetes Engine の使用を検出すると、Logging はコンテナのすべてのエラーログを検索するクエリを提案することがあります。

クエリビルダー ペインで推奨クエリを表示して実行する手順は次のとおりです。

  1. [推奨] タブをクリックします。

    一連のクエリを表示する推奨クエリタブ

  2. 推奨クエリの説明を確認します。

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

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

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

  4. クエリビルダー ペインに、クエリと [実行] または [保存] のオプションが表示されます。

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

    b. クエリを実行するには、[実行] をクリックします。 クエリビルダー ペインの [クエリのプレビュー] にクエリが表示されます。

  5. クエリを確認したら、[クエリを実行] をクリックします。推奨クエリの結果が [クエリ結果] に表示されます。

推奨クエリは、Google Cloud プロジェクトのコンテキストに基づいて動的に作成されます。ページを続けて読み込んだ際、同じクエリが同じ順序で表示されない場合があります。これは想定された動作です。

トラブルシューティング

引用符で囲まれていないテキスト

空白文字や特定の特殊文字を含まないテキスト文字列は、前後の引用符を省略できます。これを引用符で囲まれていないテキストといいます。前の例では ERROR がこれに該当します。文字列 "v1.compute.instances.insert" はピリオドを含んでいるため、引用符で囲まれています。文字列内で引用符を使用する場合には、引用符の前にバックスラッシュを追加します。

構文の問題

クエリビルダーの言語の使用中に問題が発生した場合は、次の点を確認してください。

  • クエリが構文ルールに従っていて、かっこや引用符が正しく対応しているか確認します。クエリにコメントを含めることはできません。

  • ログエントリのフィールド名が正しく入力されているか確認します。

  • ブール演算子が大文字で入力されているか確認します(ANDORNOT)。

  • グローバル制限または比較の右辺として使用されているブール式が、かっこで囲まれ明確になっているか確認します。たとえば、次の 2 つのクエリは同じように見えますが、実際は異なります。

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • 引用符で囲まれていないテキストに特殊文字を含めることはできません。正しいかわからない場合は、二重引用符を使用してください。たとえば、次のうち最初の比較は、組み込みの部分文字列演算子(:)が使用されているため、誤りです。この比較では二重引用符を使用しなければなりません。

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud logging では、クエリを二重引用符で囲む必要があります。gcloud logging コマンドで特殊文字をエスケープするために二重引用符を使用するには、フィルタ全体を単一引用符で囲みます。

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • タイムスタンプを含むクエリを作成する場合は、検索クエリボックスの下の期間セレクタから [制限なし] を選択する必要があります。