高度なログフィルタ

このガイドでは、高度なログフィルタを作成する方法を説明します。ログフィルタは、任意の数のログから特定のログエントリを指定するための式です。高度なログフィルタは、ログビューアStackdriver Logging APIコマンドライン インターフェースで使用できます。

より基本的なフィルタリング オプションについては、基本ログフィルタをご覧ください。

はじめに

高度なログフィルタは、プロジェクト内のすべてのログエントリの中からサブセットを指定するブール式です。これを使用することで、次のことができます。

  • 特定のログやログサービスからログエントリを選択する。
  • 特定の時間範囲内のログエントリを選択する。
  • メタデータやユーザー定義フィールドに対する条件を満たすログエントリを選択する。
  • すべてのログエントリのサンプリング率を選択する。

高度なフィルタの使用方法

ログビューアで高度なフィルタを使用するには:

  1. GCP Console の [Stackdriver Logging] > [Logging](ログビューア)ページに移動します。

    ログビューア ページに移動

  2. ページの上部で既存の GCP プロジェクトを選択するか、新しいプロジェクトを作成します。

  3. プルダウン メニューを使用して、ログを表示するリソースを選択します。

  4. 検索フィルタ ボックスの右端にあるプルダウン矢印(▾)をクリックして、[高度なフィルタに変換] を選択します。

次のような高度なフィルタのインターフェースが表示されます。

高度なログフィルタ

このフィルタ インターフェースには、ログの選択メニューはありませんが、[フィルタを送信] ボタンはあります。ログビューアには、フィルタで指定されたすべての条件を満たすログエントリが表示されます。

次に、高度なフィルタの簡単な例を示します。

    resource.type = "gce_instance" AND
    severity >= ERROR AND
    NOT textPayload:robot

このフィルタは、Compute Engine からのログエントリのうち、重大度が ERROR 以上であり、textPayload フィールドに「robot」という文字列が含まれていないエントリと一致します。文字列の比較では大文字と小文字が区別されません。resourceseveritytextPayload の名前は LogEntry タイプで定義されます。

入力時の提案とハイライト ログビューアで高度なフィルタを入力すると、特定のログエントリ フィールドについての提案が表示される場合があります。この提案は、フィルタ言語と、ログビューアで読み込まれた実際のログエントリの両方から生成されます。提案を選択するには、TAB キーを押します。提案が表示されない場合は、CTRL キーを押しながら SPACE キーを押してみてください。フィルタ式は部分ごとに異なる色で強調表示されます。式が明るい赤色で表示されている場合、入力済みのフィルタはエラーがあるか、不完全です。

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

ベスト プラクティス: フィールド値と比較する文字列は引用符で囲むようにしてください。これにより、比較の意味が変わったり、デバッグが困難になるような誤りを防ぐことができます。文字の後に連続した文字、数字、アンダースコア(_)が続く単語の場合は、引用符を省略できます。

キーボードの使用: キーボードを使用して高度なフィルタを検索フィルタ ボックスに入力する場合、ESC キーを押して編集モードを終了してから TAB キーを押して、他のオプション(期間セレクタ プルダウン メニュー、検索フィルタ ボックスの右端にあるプルダウン矢印(▾)、[フィルタを送信] ボタンなど)に移動できます。

高度なフィルタの構文

ここでは、高度なフィルタの構文と照合方法について説明します。

構文の表記法

高度なフィルタの構文は、次の表記を使用して記述されます。

  • a = e: a は式 e の名前です。
  • a b: a の後に b が続きます。
  • a | b: 「a または b」を意味します。
  • ( e ): グループ化に使用します。
  • [ e ]: e は省略可能です。
  • { e }: e は 0 回以上繰り返すことができます。
  • "abc": 表示されるとおりに abc と記述されている必要があります。

構文の概要

このセクションでは、高度なフィルタの構文の概要を説明します。詳細については省略されている箇所もありますが、この後のセクションで説明します。

高度なフィルタは式を含む文字列です。

    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

比較は、単一の値かブール式のいずれかです。

  "The cat in the hat"
  resource.type = "gae_app"

最初の行は、単一の値を使用した比較の例です。このタイプの比較はグローバル制限になります。ログエントリの各フィールドが、has 演算子を使用して値と比較されます。この例の場合、LogEntry のエントリまたはそのペイロードに "The cat in the hat" という語句が含まれている場合、比較に成功します。

2 行目は、[FIELD_NAME] [OP] [VALUE] というブール式を使用した比較の例です。この比較の要素は次のとおりです。

  • [FIELD_NAME]: ログエントリのフィールド。たとえば resource.type です。

  • [OP]: 比較演算子。たとえば = です。

  • [VALUE]: 数値、文字列、関数またはかっこで囲まれた式。たとえば "gae_app" です。

この後の各セクションでは、フィルタや照合について詳しく説明します。

ブール演算子

ブール演算子 ANDOR短絡演算子です。NOT 演算子の優先順位が最も高く、その後に ORAND の順に続きます。たとえば、次の 2 つの式は同じ内容を表します。

a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)

比較の間の AND 演算子は省略できます。また、NOT 演算子の代わりに -(マイナス記号)を使用できます。たとえば、次の 2 つの高度なフィルタは同じ内容を表しています。

a=b AND c=d AND NOT e=F
a=b c=d -e=f

このドキュメントでは常に ANDNOT を使用します。

比較

比較の形式は次のとおりです。

[FIELD_NAME] [OP] [VALUE]

この比較の要素は次のとおりです。

  • [FIELD_NAME]: ログエントリのフィールドのパス名。フィールド名の例を次に示します。

    resource.type
    resource.labels.zone
    resource.labels.project_id
    insertId
    jsonPayload.httpRequest.protocol
    labels."compute.googleapis.com/resource_id"
    

    詳しくは、フィールドパス識別子をご覧ください。

  • [OP]: 次のいずれかの比較演算子。

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    
  • [VALUE]: 数値、文字列、関数またはかっこで囲まれた式。文字列は任意のテキストや、ブール値、列挙型の値、バイト文字列の値を表すために使用します。[VALUE] は、比較の前にフィールドの型に変換されます。

[VALUE] がかっこで囲まれた比較の組み合わせのブール値である場合、フィールド名と比較演算子が各要素に適用されます。次に例を示します。

    jsonPayload.cat = ("siamese" OR "shorthair")
    jsonPayload.animal : ("nice" AND "pet")

最初の比較は、フィールド cat の値が「siamese」または「shorthair」であることを確認します。次の比較は、フィールド animal の値に「nice」と「pet」の両方の単語が含まれていることを確認します(順序は関係ありません)。

フィールドパス識別子

すべてのログエントリは、LogEntry タイプのインスタンスです。比較の左側にある(開始の)識別子は、LogEntry タイプで定義されたフィールドでなければなりません。使用可能な識別子とその値の詳細については、LogEntry タイプをご覧ください。

ログエントリ フィールドの最新のリストは、次のとおりです。該当する場合は、各フィールドの後に、そのフィールドの次の階層の名前が示されています。

  • httpRequest: {cacheFillBytescacheHitcacheLookupcacheValidatedWithOriginServerlatencyprotocolrefererremoteIprequestMethodrequestSizerequestUrlresponseSizeserverIpstatususerAgent}
  • insertId
  • jsonPayload {変数}
  • labels {変数}
  • logName
  • metadata {systemLabelsuserLabels}
  • operation {idproducerfirstlast}
  • protoPayload {@type、変数}
  • receiveTimestamp
  • resource {typelabels}
  • severity
  • sourceLocation: {filelinefunction}
  • spanId
  • textPayload
  • timestamp
  • trace

以下に、比較で使用できるフィールドパス識別子の例を示します。

  • resource.type: 最初のパス識別子が resource の場合、次の識別子は MonitoredResource タイプのフィールドにする必要があります。

  • httpRequest.latency: 最初のパス識別子が httpRequest の場合、次の識別子は HttpRequest タイプのフィールドにする必要があります。

  • labels.[KEY]: 最初のパス識別子が labels の場合、次の識別子 [KEY] は、labels フィールドに表示される Key-Value ペアのキーのうちの 1 つである必要があります。

  • logName: logName フィールドは文字列であるため、その後にサブフィールド名を続けることはできません。

オブジェクトまたは配列を参照するフィールドパス識別子の使用方法については、オブジェクト タイプと配列タイプをご覧ください。

モニタリング対象リソースタイプ

検索を高速化するには、モニタリング対象リソースタイプを指定します。リソースタイプの一覧については、モニタリング対象リソースタイプをご覧ください。

たとえば、Compute Engine VM はリソースタイプ gce_instance を使用し、Amazon EC2 インスタンスは aws_ec2_instance を使用します。次の例では、検索範囲を両方のタイプの VM に限定しています。

    resource.type = ("gce_instance" OR "aws_ec2_instance")

ログでは、モニタリング対象リソースタイプ値がインデックス登録されています。部分文字列の一致を使用すると、クエリが遅くなります。

欠落しているフィールド

フィルタでフィールド名を使用していて、そのフィールドがログエントリに表示されない場合、そのフィールドは欠落未定義デフォルトのいずれかの状態にあります。

  • フィールドがログエントリのペイロード(jsonPayloadprotoPayload)に含まれているか、ログエントリの labels セクションのラベルに含まれている場合、フィールドは欠落しています。欠落したフィールドを使用してもエラーは表示されませんが、このフィールドを使用する比較はすべて無応答で失敗します。

    例: jsonPayload.nearest_storeprotoPayload.name.nickname

  • フィールドが LogEntry タイプで定義されている場合、フィールドはデフォルトの状態になっています。フィールドが存在し、デフォルト値が設定されている場合と同様に比較が実行されます。

    例: httpRequest.remoteIptraceoperation.producer

  • それ以外の場合、フィールドは未定義です。このエラーは、フィルタが使用される前に検出されます。

    例: thudoperation.thudtextPayload.thud

フィールドの特定の値をテストせずに、欠落フィールドまたはデフォルト設定されたフィールドが存在するかどうかをテストするには、:* 比較を使用します。たとえば、次の比較は、ログエントリに operation.id フィールドが明示的に存在する場合に成功します。

operation.id:*

オブジェクトと配列のタイプ

ログエントリ フィールドには、スカラー、オブジェクトまたは配列を格納できます。

  • スカラー フィールドには、174.4-1 などの単一の値が格納されます。string もスカラーとみなされます。DurationTimestamp などの文字列に変換できるフィールドや、文字列から変換できるフィールドもスカラー型になります。

  • オブジェクト型には、次の JSON 値のような名前付き値のコレクションが格納されます。

    {"age": 24, "height": 67}
    

    オブジェクト内の値を参照できます。たとえば、jsonPayload.x に前述の値が含まれている場合、jsonPayload.x.age の値は 24 になります。

  • 配列フィールドには、すべて同じ型の値のリストが格納されます。たとえば、測定値を格納するフィールドには、数値の配列が格納されます。

    {8.5, 9, 6}
    

    比較が実行されたときに、[FIELD_NAME] が配列フィールドの場合、配列の各メンバーが [VALUE] と比較され、OR 演算子を使用して結果が結合されます。たとえば、jsonPayload.shoeSize{8.5, 9, 6} を格納する配列フィールドの場合、比較は次のようになります。

    jsonPayload.shoeSize < 7
    

    これは次と同等です。

    8.5 < 7 OR 9 < 7 OR 6 < 7
    

    この例では、全体的な比較は成功と評価されます。

値と変換

比較評価では、まず最初に、右辺の値がログエントリ フィールドのタイプに変換されます。比較ではスカラー フィールド タイプが使用できます。また、この他に、値が文字列として表される DurationTimestamp の 2 つのタイプも使用できます。スカラータイプの一覧については、スカラー プロトコル バッファタイプのリストをご覧ください。次の表は、ログフィールド タイプに変換できる値の一覧です。

フィールド タイプ 使用できるフィルタ値
bool true または false(大文字と小文字は区別しません)。たとえば True、true です。
bytes 任意の連続したバイトを含む文字列。たとえば \377\377 です。
Duration 符号付き 10 進数の後に ns、us、ms、s、m、h のいずれかの単位が続いている文字列。この期間はナノ秒単位の精度です。たとえば 3.2s です。
enum 列挙型のリテラルの名前。大文字と小文字は区別されません。たとえば WARNING(LogSeverity タイプの値)です。
double 任意の数値(符号と指数はある場合もない場合もあります)、または特殊な値の文字列(NaN、-Infinity、Infinity。先頭の大文字と小文字は区別されません)。たとえば -3.2e-8、nan です。
intNN 型のサイズを超えない符号付き整数。たとえば -3 です。
string UTF-8 でエンコードされたテキスト、または 7 ビットの ASCII テキストを含む任意の文字列。文字列内で引用符を使用する場合には、バックスラッシュでエスケープする必要があります。
Timestamp RFC 3339 形式の文字列。たとえば 2014-10-02T15:01:23.045Z です。フィルタ式では、タイムスタンプに Z または ±hh:mm でタイムゾーンを指定することができます。タイムスタンプは、ナノ秒単位の精度で表されます。
uintNN 型のサイズを超えない符号なし整数。たとえば 1234 です。

変換の試行に失敗した場合、比較も失敗します。

変換に文字列が必要な場合、スペースや演算子などの特殊文字が含まれていなければ、数字または引用符なしのテキストを使用することもできます。同様に、変換で数値が必要な場合、内容が数値である文字列を使用できます。

intNNuintNN の各タイプは、さまざまなサイズの整数型を表します(int32uint64 など)。64 ビットの整数タイプに変換する値を記述する場合、この値は 9223372036854775807 のように文字列として記述する必要があります。

ログフィールドのタイプ

ここでは、ログエントリ フィールドの型を判別する方法を説明します。

  • LogEntry タイプとそのコンポーネントのタイプで定義されたログフィールドはプロトコル バッファ フィールドです。プロトコル バッファ フィールドには明示的な型があります。

  • protoPayload オブジェクトの一部であるログフィールドもプロトコル バッファ フィールドであり、明示的な型があります。プロトコル バッファタイプの名前は、protoPayload のフィールド "@type" に格納されます。詳細については JSON マッピングをご覧ください。

  • jsonPayload 内部にあるログフィールドの型は、ログエントリの受信時にフィールドの値から推測されます。

    • 値が引用符なしの数値であるフィールドの型は double です。
    • 値が true または false であるフィールドの型は bool です。
    • 値が文字列であるフィールドの型は string です。

    長整数型(64 ビット)は、double 値として正確に表現できないため、文字列フィールドに格納されます。

  • Duration 型と Timestamp 型はプロトコル バッファ フィールドでのみ認識されます。それ以外の場合、これらの値は文字列フィールドに格納されます。

比較演算子

等式(=!=)と不等式(<<=>>=)演算子の意味は、左辺のフィールド名の基になる型によって異なります。

  • すべての数値型: 等式と不等式は通常の数値の場合での意味と同じです。
  • bool: 等式は同じブール値であることを表します。不等式は「true > false」と定義されます。
  • enum: 等式は同じ列挙値であることを表します。不等式では、列挙型リテラルの基礎となる数値を使用します。
  • Duration: 等式は同じ期間であることを表します。不等式は期間の長さに基づきます。たとえば、期間として、"1s" > "999ms" となります。
  • Timestamp: 等式は同じ時刻であることを指します。abTimestamp 値である場合、「a < b」は a の時刻が b の時刻よりも前であることを表します。
  • bytes: オペランドはバイト単位で左から順番に比較されます。
  • string: 比較では大文字と小文字は区別されません。具体的には、まず両方のオペランドが NFKC_CF Unicode 正規化により正規化され、その後に辞書式比較されます。

部分文字列演算子(:)は stringbytes に使用でき、等式演算子と同様に扱われます。ただし、右辺のオペランドが左辺の一部とだけでも一致していれば成立します。インデックス付きフィールドでの部分文字列の照合では、ログ インデックスは利用されません。

グローバル制限

比較が単一の値で構成されている場合、この比較をグローバル制限といいます。ロギングでは、has (:) 演算子を使用して、ログエントリのフィールドまたはペイロードにグローバル制限があるか確認します。グローバル制限がある場合、比較に成功します。

グローバル制限の高度フィルタの中で最も簡単なものが単一の値です。

"The Cat in The Hat"

AND 演算子や OR 演算子を使用してグローバル制限を組み合わせると、より複雑なフィルタを作成できます。たとえば、フィールドに cat が含まれているログエントリと、フィールドに hat または bat が含まれているログエントリをすべて表示するには、フィルタを次のように記述します。

(cat AND (hat OR bat))

この場合、cathatbat の 3 つのグローバル制限があります。これらのグローバル制限が個別に適用され、かっこなしで式を作成した場合と同様に結果が結合されます。

グローバル制限を使用すると、ログで特定の値を簡単に検索できます。たとえば、アクティビティ ログで GCE_OPERATION_DONE を含むエントリを検索する場合、次のフィルタを使用します。

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

グローバル制限は簡単に実行できますが、速度は遅くなる場合があります。ログエントリの迅速な検索をご覧ください。

関数

高度なフィルタでは、組み込み関数をグローバル制限として使用できます。

function = identifier ( [ argument { , argument } ] )

argument は値、フィールド名、またはかっこで囲まれた式です。これらの関数については、以降のセクションで説明します。

sample

sample 関数は、ログエントリの総数の一部を選択します。

sample([FIELD], [FRACTION])

[FIELD] はログエントリ内のフィールド名です(logNamejsonPayload.a_field など)。フィールドの値によって、ログエントリがサンプルに含まれるかどうかが決まります。フィールド タイプは文字列または数値にする必要があります。すべてのログエントリがそのフィールドに異なる値を持つため、[FIELD]insertId に設定するのも良い選択肢です。

[FRACTION] は、[FIELD] に値があるログエントリの中で対象にするエントリの割合です。0.0 より大きく 1.0 以下の数値にします。たとえば、0.01 を指定すると、[FIELD] に値があるすべてのログエントリの約 1% がサンプルに含まれます。[FRACTION] が 1 の場合、[FIELD] に値があるすべてのログエントリが選択されます。

: 次のフィルタは、ログ syslog のログエントリの約 25% を返します。

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

詳細: ログエントリをサンプルに追加するかどうかは、ハッシュ値に基づく決定論的アルゴリズムによって決まります。結果のサンプルの精度は、ハッシュ値の分布によって変わります。ハッシュ値が一様に分布していない場合、結果のサンプルが偏ることがあります。[FIELD] の値が常に同じである最悪のシナリオでは、結果のサンプルにすべてのログエントリの [FRACTION] が含まれるか、ログエントリがまったく含まれないかのいずれかになります。

ログエントリに [FIELD] が含まれる場合、次のように処理されます。

  • 値のハッシュが計算されます。
  • ハッシュ値(数値)が、ハッシュの最大許容値で除算されます。
  • 結果の端数が [FRACTION] 以下の場合、ログエントリはサンプルに含められます。それ以外の場合はサンプルから除外されます。

ログエントリに [FIELD] が含まれない場合、次のように処理されます。

  • [FIELD] がログエントリのペイロードまたは labels セクションの一部である場合、[FRACTION] が 1 であっても、ログエントリはサンプルに含められません。
  • それ以外の場合、ログエントリは [FIELD] を含んでいるかのように処理されます。その際に、[FIELD] の値はデフォルト値になります。デフォルト値は、LogEntry タイプによって決まります。欠落フィールドとデフォルト フィールドについて詳しくは、欠落しているフィールドをご覧ください。

デフォルト フィールドがあるログエントリをサンプルから除外するには、field-exists 演算子 :* を使用します。次のフィルタは、field の値を明示的に指定したログエントリの 1% のサンプルを生成します。

field:* AND sample(field, 0.01)

ip_in_net

ip_in_net 関数は、ログエントリの IP アドレスがサブネットに含まれているかどうかを判別します。これを使用して、リクエストが内部ソースと外部ソースのどちらから来たものかを知ることができます。次に例を示します。

ip_in_net([FIELD], [SUBNET])

[FIELD] は、IP アドレスまたは範囲を含むログエントリ内の文字列値フィールドです。フィールドは繰り返すことができ、その場合、サブネットに含まれるアドレスまたは範囲を持つ必要があるのは、繰り返されるフィールドのうち 1 つのみです。

[SUBNET] は、IP アドレスまたは範囲の文字列定数です。このセクションで後述するように、[SUBNET] が有効な IP アドレスまたは範囲でない場合はエラーになります。

: 次のフィルタは、ログ my_log に含まれるログエントリのペイロード内の IP アドレスをテストします。

    logName = "projects/my_project/logs/my_log" AND
    ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

詳細: ログエントリ内の [FIELD] が欠落しているか、デフォルトになっているか、または有効な IP アドレスや範囲が含まれていない場合、関数は false を返します。欠落フィールドとデフォルト フィールドについて詳しくは、欠落しているフィールドをご覧ください。

サポートされている IP アドレスと範囲の例を以下に示します。

  • IPv4: 10.1.2.3
  • IPv4 サブネット: 10.1.2.0/24
  • CIDR IPv6: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • CIDR IPv6 サブネット: 1:2::/48

時間で検索する

高度なフィルタ インターフェースでは、表示するログエントリの日時に制限を設定できます。たとえば、次の式をフィルタに追加すると、ログビューアには指定された 30 分間のログエントリだけが表示され、他の日時にスクロールできなくなります。

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

タイムスタンプ フィルタを作成する場合には、上の形式で日付と時刻を指定する必要があります。

期間セレクタのメニューで、表示するログエントリの日付と時刻を設定することもできます。詳しくは、時間までスクロールをご覧ください。

ログエントリの迅速な検索

ログエントリのフィルタリングや照会では、次のようにします。

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

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

インデックス フィールドには正確な値を指定します。部分文字列の一致は使用しないでください。次のログエントリ フィールドがインデックス登録されています。

一時的なフィールド インデックス

Stackdriver Logging がログエントリを受信した後、一定時間に限り 3 つの追加ログエントリ フィールドが部分的にインデックス登録されます。システムの問題に迅速に対応する必要がある場合、これらのフィールドを検索すると便利なことがあります。Stackdriver Logging では、これらの 3 つのフィールドのインデックス登録の方法が、将来的に、通知なく変更される場合があります。

  • severity: NOTICE(100)から EMERGENCY(900)までの重大度値がインデックス登録されます。インデックスを利用するには、インデックスに登録されている、この範囲の値のみを検索します。

  • httpRequest.status: 201 から 511 までのステータス値がインデックス登録されます。インデックスを利用するには、インデックスに登録されている、この範囲の値のみを検索します。

  • operation.id: これらのフィールドの値はすべてインデックス登録されます。インデックスを利用するには、等式演算子を使用してこのフィールドを検索します。部分文字列の検索は使用しないでください。

最近のログエントリでこれらのフィールドを定期的に検索する場合は、timestamp フィールドを使用して検索対象期間を限定することも検討してください。

ログ、ログエントリ、時間の最小化

検索対象のログの数、ログエントリの数、または期間を少なくすると、検索が速くなります。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

これらのタイムスタンプの値を次のフィルタで使用します。Stackdriver 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" を含むログエントリを検索します。これは基本フィルタ インターフェースと同じです。

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

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

トラブルシューティング

キーボードを使用して高度なフィルタを検索フィルタ ボックスに入力した後、ページの他のメニューに移動するには、ESC キーを押して編集モードを終了してから、TAB キーを押して他のオプションに移動します。

高度なフィルタに問題がある場合は、次の点を確認してください。

  • フィルタが構文ルールに従っていて、かっこや引用符が正しく対応しているか確認します。

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

  • ブール演算子が大文字で入力されているか確認します(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."'
    
  • ログビューアの基本フィルタの検索式は、高度なフィルタの検索式とは異なります。詳しくは、基本フィルタと高度なフィルタの違いをご覧ください。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。