トレース フィルタを使用して、Cloud Trace から一連のトレースを選択します。 トレース フィルタは、次のいずれかの方法で使用してください。
listAPI メソッドを使用するクエリで、フィルタ パラメータとして使用する。分析レポートを作成するときに、リクエスト フィルタ パラメータとして使用する。
[Trace エクスプローラ] ページで、[フィルタ] filter_list フィールドとして使用する。これらのフィルタの作成と変更の詳細については、最近のトレースを表示するをご覧ください。
フィルタを使用すると、表示されるトレースが満たすべき条件を 1 つ以上指定できます。フィルタ構文を使用すると、完全一致の場合または接頭辞テストの場合を定義できます。一致はすべて大文字と小文字が区別されます。
フィルタの概要
トレース フィルタは、キーワードと呼ばれる一連の比較で構成されます。トレースは、選択するフィルタ内のすべてのキーワードと一致する必要があります。たとえば、次のフィルタは、レイテンシが 1 秒以上で、/modules.GetNumInstances という名前のスパンを含むトレースに一致します。
+span:/modules.GetNumInstances latency:1s
すべての文字列比較では大文字と小文字が区別されます。
ブール値の属性
ブール属性の値を指定するには、false に 0、true に 1 を使用します。次に例を示します。
Client:0
特殊文字
スペースまたはコロン（:）が含まれている値を検索するには、値を二重引用符（"）文字で囲みます。次に例を示します。
label:"Notice: This value contains spaces and a colon"
二重引用符またはバックスラッシュ（\）文字が含まれる文字列を引用符で囲んで検索文字列として指定するには、その文字をバックスラッシュでエスケープします。次に例を示します。
label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"
フィルタの構文
次のテーブルとこのページの別の場所では、NAME はフィールドの名前、VALUE は Key-Value ペアの値を表します。文字列 _PREFIX と _EXACT は、テストが接頭辞テストか完全一致かを視覚表示で示しています。たとえば、root:[NAME_PREFIX] は、ルートスパンの名前を [NAME_PREFIX] で始める必要があることを意味します。
次の表に、Cloud Trace で使用されるフィルタの構文を一覧表示します。
| Trace API [分析レポート] ページの [リクエスト フィルタ] |
[Trace エクスプローラ] ページの [フィルタ] |
|---|---|
root:[NAME_PREFIX] |
RootSpan:[NAME_PREFIX] |
+root:[NAME_EXACT] |
RootSpan:+[NAME_EXACT] |
span:[NAME_PREFIX] |
SpanName:[NAME_PREFIX] |
+span:[NAME_EXACT] |
SpanName:+[NAME_EXACT] |
[NAME_PREFIX] |
RootSpan:[NAME_PREFIX] |
label:[LABEL_KEY] |
HasLabel:[LABEL_KEY] |
[LABEL_KEY]: [VALUE_PREFIX] |
[LABEL_KEY]:[VALUE_PREFIX]* |
+[LABEL_KEY]: [VALUE_EXACT] |
[LABEL_KEY]:+[VALUE]* |
^[LABEL_KEY]: [VALUE_PREFIX] |
[LABEL_KEY]:^[VALUE_PREFIX]* |
+^[LABEL_KEY]: [VALUE_EXACT] |
[LABEL_KEY]:^+[VALUE_EXACT]*, † |
method:[VALUE_PREFIX] |
Method:[VALUE_PREFIX] |
latency:10ms |
MinLatency:10ms |
url:[VALUE_PREFIX] |
URL:[VALUE_PREFIX] |
* 次のトレース キーワードはラベルキーとして使用しないでください: root、span、label、method、latency、urlこれらのラベルキーを持つトレースはクエリできません。
† [Trace エクスプローラ] ページでは、Enter キーを押すとアノテーション +^ が ^+ に変換されます。
このページの残りの部分では、Trace API を使用する場合のフィルタと、[分析レポート] ページの [リクエスト フィルタ] について説明します。[Trace エクスプローラ] ページで [フィルタ] フィールドを使用している場合は、前のテーブルのマッピングを使用して同等の式を作成できます。
リクエスト フィルタの例
以下では、フィルタ キーワードについて説明します。
root:[NAME_PREFIX]トレースのルートスパン名は [NAME_PREFIX] で始まる必要があります。たとえば、次のフィルタは
"/_ah/background"という名前のトレースに一致しますが、"/_ahx/background"という名前のトレースには一致しません。root:/_ah/+root:[NAME]トレースのルートスパン名は [NAME] に完全に一致する必要があります。例:
+root:/_ah/background[NAME_PREFIX]この構文は
root:[NAME_PREFIX]の省略形です。+[NAME]この構文は
+root:[NAME]の省略形です。span:[NAME_PREFIX]トレースには、[NAME_PREFIX] で始まる名前のスパンが少なくとも 1 つ必要です。 例:
span:/modules.+span:[NAME]トレースには、名前が [NAME] に完全に一致するスパンが少なくとも 1 つ必要です。次に例を示します。
span:/modules.GetNumInstanceslatency:[DURATION]トレースには、全体で [DURATION] 以上となるレイテンシが必要です。時間は、整数の後に単位指定子（
sは秒、msはミリ秒、nsはナノ秒）が続く形で表されます。単位指定子がない場合、単位はミリ秒です。たとえば、次の 4 つの時間は同じです。12s 12000ms 12000000ns 12000label:[LABEL_KEY]トレースには、完全に一致する指定されたラベルキーが含まれている必要があります。ラベルの値が指定されていても、その値は影響しません。次に例を示します。
label:/http/url[LABEL_KEY]:[VALUE_PREFIX]トレースには完全に一致する指定されたラベルキーが含まれている必要があり、ラベルの値は [VALUE_PREFIX] で始まる必要があります。たとえば、次のキーワードは、App Engine のバージョンが
"2017"で始まるトレースと一致します。g.co/gae/app/module_version:2017+[LABEL_KEY]:[VALUE_EXACT]トレースには、完全に一致する指定されたラベルキーと値が含まれている必要があります。 次に例を示します。
+g.co/gae/app/module_version:201750925t173233.387410594824284458method:[VALUE_PREFIX]この構文は、ラベルテスト
/http/method:[VALUE_PREFIX]の省略形です。+method:[VALUE_EXACT]この構文は、ラベルテスト
+/http/method:[VALUE_EXACT]の省略形です。url:[VALUE_PREFIX]この構文は、ラベルテスト
/http/url:[VALUE_PREFIX]の省略形です。+url:[VALUE_EXACT]この構文は、ラベルテスト
+/http/url:[VALUE_EXACT]の省略形です。
ルートスパン検索の例
検索キーワードをルートスパンのみに限定するには、（^）を検索キーワードの前、ただしオプションの（+）がある場合はその後に追加します。[Trace エクスプローラ] ページの [フィルタ] フィールドでは、アノテーション +^ を追加すると、Enter キーが押されたとき、^+ に変換されます。
以下に、ルートスパンのみの検索キーワードとその等値を示します。
^label:[LABEL_KEY]- これは
label:[LABEL_KEY]のルートスパン検索です。 ^[LABEL_KEY]:[VALUE_PREFIX]- これは
[LABEL_KEY]:[VALUE_PREFIX]のルートスパン検索です。 +^[LABEL_KEY]:[VALUE]- これは
+[LABEL_KEY]:[VALUE]のルートスパン検索です。 ^method:[VALUE_PREFIX]- これは
method:[VALUE_PREFIX]のルートスパン検索です。 +^method:[VALUE]- これは
+method:[VALUE]のルートスパン検索です。 ^url:[VALUE_PREFIX]- これは
url:[VALUE_PREFIX]のルートスパン検索です。 +^url:[VALUE]- これは
+url:[VALUE]のルートスパン検索です。 ^span:[NAME_PREFIX]- これは
root:[NAME_PREFIX]と同じです。 +^span:[NAME]- これは
+root:[NAME]と同じです。
用語が混在するクエリを作成することで、検索をさらにカスタマイズできます。 次に例を示します。
+^url:/main /images method:200
ルートスパンのラベル「/http/url」が「/ main」で、ルートスパンの名前の接頭辞に「/images」が付いており、スパンのラベル/http/methodが 200 の値に設定されている場合、トレースに一致します。
トラブルシューティング
このセクションでは、トラブルシューティングの内容を示します。
パフォーマンスの低下
トレース フィルタが複雑な場合、実行に時間がかかり、タイムアウトになる可能性があります。パフォーマンスを向上させるには、フィルタを単純化します。
結果がない
フィルタからトレースが返されない場合は、次の点を確認してください。
比較を隔てるもの以外に、フィルタにスペースが含まれていないことを確認します。
フィルタ内のすべての単語の大文字と小文字およびスペルが正しいことを確認します。たとえば、
method:GETなどのキーワードのスペルを間違えた場合、フィルタはlabel:method:GETと解釈され、どのトレースとも一致しません。フィルタ条件を 1 つずつテストするには、トレースリスト フィルタまたは API Explorer を使用します。 キーワードのうちの 1 つが結果を返さない場合、それが原因と考えられます。