このガイドでは、複数のログから一連のログエントリを指定できる高度なログクエリの式を記述する方法を説明します。高度なログクエリは、ログビューア、Logging API、gcloud コマンドライン ツールで使用できます。
より基本的なクエリ オプションについては、基本ログフィルタをご覧ください。
ログの検索でおすすめのクエリの一覧については、サンプルクエリをご覧ください。
はじめに
高度なログクエリとは、プロジェクトのログエントリ全体のうちの特定部分を指定するブール式のことです。これは、次のことに使用できます。
- 特定のログやログサービスからログエントリを選択する。
- 特定の時間範囲内のログエントリを選択する。
- メタデータやユーザー定義フィールドに対する条件を満たすログエントリを選択する。
- すべてのログエントリのサンプリング率を決める。
高度なログクエリを使ってみる
ログビューアで高度なログクエリを使用するには、次の手順に従います。
Cloud Console の [Stackdriver Logging] > [ログ]（ログビューア）ページに移動します。
ページの上部で既存の Google Cloud プロジェクトを選択するか、新しいプロジェクトを作成します。
プルダウン メニュー arrow_drop_down を使用して、ログを表示するリソースを選択します。
検索クエリボックスでプルダウン メニュー arrow_drop_down をクリックして高度なフィルタに変換を選択します。
ログクエリは、ログエントリの特定のセットを選択できるようになっているため、ユーザー インターフェースでは「フィルタ」のラベルが付いています。
高度なログクエリのインターフェースが表示されます。
このクエリ インターフェースには、ログの選択メニューがなく、[フィルタを送信] ボタンが備わっています。ログビューアには、クエリで指定された条件のすべてを満たすログエントリが表示されます。
高度なログクエリの簡単な例を次に示します。
resource.type = "gce_instance" AND
severity >= ERROR AND
NOT textPayload:robot
このクエリは、重大度が少なくとも ERROR で、かつ、textPayload フィールドが文字列 robot を含んでいない Compute Engine のログエントリと一致します。文字列の比較では、大文字と小文字は区別されません。名前 resource、severity、textPayload は、LogEntry 型で定義されます。
入力時の提案と強調表示: ログビューアに高度なログクエリを入力すると、特定のログエントリ フィールドに対する提案が表示される場合があります。この提案は、クエリ言語と、ログビューアで読み込まれた実際のログエントリの両方から生成されます。提案を選択するには、TAB キーを押します。提案が表示されない場合は、CTRL + SPACE キーを押してみてください。クエリ式の異なるパーツは、異なる色で強調表示されます。式が明るい赤色で表示されている場合、入力されたクエリにエラーがあるか、式が不完全です。
引用符で囲まれていないテキスト: 空白文字や特定の特殊文字を含まないテキスト文字列は、前後の引用符を省略できます。これを「引用符で囲まれていないテキスト」といいます。前の例では ERROR と robot がこれに該当します。文字列 "v1.compute.instances.insert" はピリオドを含んでいるため、引用符で囲まれています。文字列内で引用符を使用する場合には、引用符の前にバックスラッシュを追加します。
ベスト プラクティス: フィールド値と比較する文字列は引用符で囲むようにしてください。これにより、比較の意味が変わる誤りや、デバッグが困難な誤りを防ぐことができます。英字の後に、英字、数字、アンダースコア（
_）の列が続く単語の場合は、引用符を省略できます。
キーボードの使用: キーボードを使用して検索フィルタ ボックスに高度なログクエリを入力しているときは、ESC キーを押して編集モードを終了できます。次に TAB キーを押すと、プルダウン メニュー arrow_drop_down や、[フィルタを送信] ボタンなどの他のオプションに移動できます。
高度なログクエリの構文
ここでは、高度なログクエリの構文と照合方法について説明します。
構文の表記法
高度なログクエリの構文は、次の表記を使用して記述されます。
- 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"
以降のセクションでは、クエリと照合についてさらに詳しく説明します。
ブール演算子
ブール演算子 AND と OR は短絡評価の演算子です。NOT 演算子の優先順位が最も高く、その後に OR と AND が順に続きます。たとえば、次の 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
このドキュメントでは常に AND と NOT を使用します。
比較
比較の形式は次のとおりです。
[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: {cacheFillBytes,cacheHit,cacheLookup,cacheValidatedWithOriginServer,latency,protocol,referer,remoteIp,requestMethod,requestSize,requestUrl,responseSize,serverIp,status,userAgent}insertIdjsonPayload{ variable }labels{ variable }logNamemetadata{systemLabels,userLabels}operation{id,producer,first,last}protoPayload{@type, variable }receiveTimestampresource{type,labels}severitysourceLocation: {file,line,function}spanIdtextPayloadtimestamptrace
以下に、比較で使用できるフィールドパス識別子の例を示します。
resource.type: 最初のパス識別子が
resourceの場合、次の識別子は MonitoredResource タイプのフィールドにする必要があります。httpRequest.latency: 最初のパス識別子が
httpRequestの場合、次の識別子は HttpRequest タイプのフィールドにする必要があります。labels.[KEY]: 最初のパス識別子が
labelsの場合、次の識別子[KEY]はlabelsフィールドにある Key-Value ペアのどちらかを指定する必要があります。logName:
logNameフィールドは文字列のため、その後にサブフィールド名を続けることはできません。
オブジェクトまたは配列を参照するフィールドパス識別子の使用に関する詳細は、このページのオブジェクトと配列の型をご覧ください。
モニタリング対象リソースタイプ
検索を高速化するには、モニタリング対象リソースタイプを指定します。リソースタイプの一覧については、モニタリング対象リソースタイプをご覧ください。
たとえば、Compute Engine VM はリソースタイプ gce_instance を使用し、Amazon EC2 インスタンスは aws_ec2_instance を使用します。次の例では、検索範囲を両方の種類の VM に限定しています。
resource.type = ("gce_instance" OR "aws_ec2_instance")
ログでは、モニタリング対象リソースタイプ値がインデックス登録されています。部分文字列の一致を使用すると、クエリが遅くなります。
欠落しているフィールド
クエリでフィールド名を使用していて、そのフィールドがログエントリに表示されない場合、そのフィールドは欠落、未定義、デフォルトのいずれかの状態にあります。
フィールドがログエントリのペイロード（
jsonPayloadやprotoPayload）に含まれているか、ログエントリのlabelsセクションのラベルに含まれている場合、フィールドは欠落しています。欠落しているフィールドを使用してもエラーは表示されませんが、このフィールドを使用する比較はすべて無応答で失敗します。例:
jsonPayload.nearest_store、protoPayload.name.nicknameフィールドが LogEntry 型で定義されている場合、フィールドはデフォルトの状態になっています。フィールドが存在し、デフォルト値が設定されている場合と同様に比較が実行されます。
例:
httpRequest.remoteIp、trace、operation.producerそれ以外の場合、フィールドは未定義です。このエラーは、クエリが使用される前に検出されます。
例:
thud、operation.thud、textPayload.thud
フィールドの特定の値をテストせずに、欠落フィールドまたはデフォルト設定されたフィールドが存在するかどうかをテストするには、:* 比較を使用します。たとえば、次の比較は、ログエントリに operation.id フィールドが明示的に存在する場合に成功します。
operation.id:*
オブジェクトと配列の型
ログエントリ フィールドには、スカラー、オブジェクトまたは配列を格納できます。
スカラー フィールドには、
174.4や-1などの単一の値が格納されます。stringもスカラーとみなされます。DurationやTimestampなどの文字列に変換できるフィールドや、文字列から変換できるフィールドもスカラー型になります。オブジェクト型には、次の 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この例では、全体的な比較は成功と評価されます。
値と変換
比較評価では、まず最初に、右辺の値がログエントリ フィールドの型に変換されます。比較ではスカラー フィールド型が使用できます。また、この他に、値が文字列として表される Duration と Timestamp の 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 形式または ISO 8601 形式の文字列。例: 2014-10-02T15:01:23.045Z（RFC 3339）、2014-10-02（ISO 8601）。クエリ式では、RFC 3339 形式のタイムスタンプに Z または ±hh:mm を付けてタイムゾーンを指定できます。タイムスタンプは、ナノ秒単位の精度で表されます。 |
uintNN |
型のサイズを超えない符号なし整数。たとえば 1234 です。 |
変換の試行に失敗した場合、比較も失敗します。
変換に文字列が必要な場合、スペースや演算子などの特殊文字が含まれていなければ、数字または引用符なしのテキストを使用することもできます。同様に、変換で数値が必要な場合、内容が数値の文字列を使用できます。
intNN 型と uintNN 型は、さまざまなサイズの整数型を表します（int32 や uint64 など）。64 ビットの整数型に変換する値を記述する場合、この値は「9223372036854775807」のように文字列として記述する必要があります。
ログフィールドのタイプ
ここでは、ログエントリ フィールドの型を判別する方法を説明します。
LogEntry 型とそのコンポーネントの型で定義されたログフィールドはプロトコル バッファ フィールドです。プロトコル バッファ フィールドには明示的な型があります。
protoPayloadオブジェクトの一部であるログフィールドもプロトコル バッファ フィールドであり、明示的な型があります。プロトコル バッファタイプの名前は、protoPayloadのフィールド"@type"に格納されます。詳細については、JSON マッピングをご覧ください。jsonPayload内部にあるログフィールドの型は、ログエントリの受信時にフィールドの値から推測されます。- 値が引用符なしの数値であるフィールドの型は
doubleです。 - 値が
trueまたはfalseのフィールドの型はboolです。 - 値が文字列であるフィールドの型は
stringです。
長整数型（64 ビット）は、
double値として正確に表現できないため、文字列フィールドに格納されます。- 値が引用符なしの数値であるフィールドの型は
Duration型とTimestamp型はプロトコル バッファ フィールド {:class="external"} でのみ認識されます。それ以外の場合、これらの値は文字列フィールドに格納されます。
比較演算子
等式（=、!=）と不等式（<、<=、>、>=）の演算子の意味は、左辺のフィールド名のタイプによって異なります。
- すべての数値型: 等式と不等式は通常の数値の場合での意味と同じです。
bool: 等式は同じブール値であることを表します。不等式は「true>false」で定義されます。enum: 等式は同じ列挙値であることを表します。不等式では、列挙型リテラルの基礎となる数値を使用します。Duration: 等式は同じ期間であることを表します。不等式は期間の長さに基づきます。たとえば、期間として、"1s">"999ms"となります。Timestamp: 等式は同じ時刻であることを指します。a と b がTimestamp値である場合、「a < b」は a の時刻が b の時刻よりも前であることを表します。bytes: オペランドはバイト単位で左から順番に比較されます。string: 比較では大文字と小文字は区別されません。具体的には、まず両方のオペランドが NFKC_CF Unicode 正規化により正規化され、その後に辞書式比較されます。
部分文字列演算子（:）は string と bytes に使用でき、等式演算子と同様に扱われます。ただし、右辺のオペランドが左辺の一部とだけでも一致していれば成立します。インデックス付きフィールドでの部分文字列の照合では、ログ インデックスは利用されません。
グローバル制限
比較が単一の値で構成されている場合、この比較をグローバル制限といいます。Logging では、has（:）演算子を使用して、ログエントリのフィールドまたはペイロードにグローバル制限があるか確認します。グローバル制限がある場合、比較に成功します。
グローバル制限の高度なログクエリの中で最も簡単なものが単一の値です。
"The Cat in The Hat"
AND 演算子や OR 演算子を使用してグローバル制限を組み合わせると、より複雑なクエリを作成できます。たとえば、フィールドに cat が含まれているログエントリと、フィールドに hat または bat が含まれているログエントリをすべて表示するには、クエリを次のように記述します。
(cat AND (hat OR bat))
この場合、cat、hat、bat の 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([FIELD], [FRACTION])
[FIELD] はログエントリ内のフィールド名です（logName や jsonPayload.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
log_id
log_id 関数により、具体的な logName が簡単な記述でフィルタできます。次に例を示します。
log_id([NAME])
[NAME] は、logName フィールドの末尾に一致する文字列で、クエリにより照合されます。[NAME] は一致処理の前に URL エンコードされます。つまり、/ 文字は自動的に %2F に変換されます。
例: 次のクエリはログタイプ cloudaudit.googleapis.com/activity を探します。
log_id("cloudaudit.googleapis.com/activity")
このクエリは、すべてのプロジェクトで logName フィールドの末尾が "cloudaudit.googleapis.com%2Factivity" で終わるものと一致します。たとえば、次の logName フィールドはすべて一致します。
"projects/project_1/logs/cloudaudit.googleapis.com%2Factivity"
"projects/project_2/logs/cloudaudit.googleapis.com%2Factivity"
"projects/project_3/logs/cloudaudit.googleapis.com%2Factivity"
時間で検索する
高度なログクエリ インターフェースでは、表示するログエントリの日時に制限を設定できます。たとえば、次の式をクエリに追加すると、ログビューアには指定された 30 分間のログエントリだけが表示され、他の日時にスクロールできなくなります。
timestamp >= "2016-11-29T23:00:00Z"
timestamp <= "2016-11-29T23:30:00Z"
タイムスタンプを使用してクエリを作成する場合には、上の形式で日付と時刻を指定する必要があります。また、検索クエリボックスの下の時間範囲セレクタから [制限なし] を選択する必要があります。
ログエントリの迅速な検索
ログエントリを効率的に検索する方法は次のとおりです。
- インデックス フィールドを使用して検索する。
- 検索対象のログエントリの数を最小限に抑える。
インデックス フィールドの使用
インデックスを活用するには、等価演算子を使用してインデックス フィールドに正確な値を指定します。部分文字列の一致は使用しないでください。
次の LogEntry フィールドがインデックス化されています。
- httpRequest.status
- logName
- operation.id
- resource.type
- resource.labels のインデックス付きリソースラベル
- severity
- 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
これらのタイムスタンプの値を次のクエリで使用します。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-access と apache-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_logrequest_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 エンコードされている必要があります。比較に等価演算子を使用すると検索をスピードアップできます。詳細については、監査ログについてをご覧ください。unicornunicornを含むログエントリを任意のフィールドから検索します。大文字と小文字は区別しません。フィールド比較に含まれない検索語は、「すべてのフィールド」クエリです。unicorn phoenix一部のフィールドに
unicornが含まれていて、かつ、一部のフィールドにphoenixが含まれているログエントリを検索します。textPayload:(unicorn phoenix)順序は関係なく、
textPayloadフィールドにunicornとphoenixの両方が含まれているログエントリを検索します。2 つのキーワードは暗黙にANDで結合されます。textPayload:"unicorn phoenix"textPayloadフィールドに文字列"unicorn phoenix"を含むログエントリを検索します。これは基本クエリ インターフェースと同じです。timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"30 分間のログエントリを検索します。
トラブルシューティング
キーボードの操作
キーボードを使用して高度なクエリを検索クエリボックスに入力した後、ページの他のメニューに移動するには、ESC キーを押して編集モードを終了してから、TAB キーを押して他のオプションに移動します。
構文の問題
高度なクエリの式に問題がある場合は、次の点を確認してください。
クエリが構文ルールに従っていて、かっこや引用符が正しく対応しているか確認します。クエリにコメントを含めることはできません。
ログエントリのフィールド名が正しく入力されているか確認します。
ブール演算子が大文字で入力されているか確認します（
AND、OR、NOT）。グローバル制限または比較の右辺として使用されているブール式が、かっこで囲まれ明確になっているか確認します。たとえば、次の 2 つのクエリは同じように見えますが、実際は異なります。
insertId = "ABC-1" OR "ABC-2" # ERROR!? insertId = ("ABC-1" OR "ABC-2")引用符で囲まれていないテキストに特殊文字を含めることはできません。正しいかわからない場合は、二重引用符を使用してください。たとえば、次のうち最初の比較は、組み込みの部分文字列演算子（
:）が使用されているため、誤りです。この比較では二重引用符を使用しなければなりません。insertId = abc:def # ILLEGAL! insertId = "abc:def"gcloudコマンドライン ツールでは、フィルタを二重引用符で囲む必要があります。gcloud loggingコマンドで特殊文字をエスケープするために二重引用符を使用するには、フィルタ全体を単一引用符で囲みます。gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'ログビューアの基本クエリの検索式は、高度なログクエリの検索式とは異なります。詳細については、基本クエリと高度なクエリの違いをご覧ください。
タイムスタンプを含むクエリを作成している場合は、検索クエリボックスの下の時間範囲セレクタから [制限なし] を選択する必要があります。