Cloud Trace フィルタ

トレース フィルタを使用して、Cloud Trace から一連のトレースを選択します。 トレース フィルタは、次のいずれかの方法で使用してください。

  • list API メソッドを使用するクエリで、フィルタ パラメータとして使用する。

  • 分析レポートを作成するときにリクエスト フィルタ パラメータとして使用する。

  • [トレースリスト] ページで、[フィルタ] フィールドとして使用する。こうしたフィルタの作成と変更の詳細については、フィルタをご覧ください。

フィルタを使用すると、表示されるトレースが満たすべき条件を 1 つ以上指定できます。フィルタ構文を使用すると、完全一致の場合または接頭辞テストの場合を定義できます。一致はすべて大文字と小文字が区別されます。

次の表に、Cloud Trace で使用されるフィルタの構文を示します。

Trace API
[分析レポート] ページの [リクエスト フィルタ]
[トレースリスト] ページの [フィルタ]
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:[LABEL_KEY]:[VALUE_PREFIX]
+[LABEL_KEY]: [VALUE_PREFIX] Label:[LABEL_KEY]:+[VALUE_PREFIX]
^[LABEL_KEY]: [VALUE_PREFIX] Label:[LABEL_KEY]:^[VALUE_PREFIX]
+^[LABEL_KEY]: [VALUE_PREFIX] Label:[LABEL_KEY]:^+[VALUE_PREFIX]*
method:[VALUE_PREFIX] LABEL:method:[VALUE_PREFIX]
latency:10ms Latency:10ms
url:[VALUE_PREFIX] URL:[VALUE_PREFIX]

* トレースリストページでは、Enter キーを押すと、アノテーション +^^+ に変換されます。

このページの残りの部分では、Trace API を使用する場合のフィルタと、[分析レポート] ページの [リクエスト フィルタ] について説明します。[トレースリスト] ページで [フィルタ] フィールドを使用する場合は、上の表のマッピングを使用して、同等の式を作成できます。

フィルタの構文

トレース フィルタは、キーワードと呼ばれる一連の比較で構成されます。トレースは、選択するフィルタ内のすべてのキーワードと一致する必要があります。たとえば、次のフィルタは、レイテンシが 1 秒以上で、/modules.GetNumInstances という名前のスパンを含むトレースに一致します。

+span:/modules.GetNumInstances latency:1s

すべての文字列比較では大文字と小文字が区別されます。フィルタ キーワードは、以下のとおりです。

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.GetNumInstances
latency:[DURATION]

トレースには、全体で [DURATION] 以上となるレイテンシが必要です。時間長は、整数の後に単位指定子(s は秒、ms はミリ秒、ns はナノ秒)が続く形で表されます。単位指定子がない場合、単位はミリ秒です。たとえば、次の 4 つの時間長は同じです。

 12s 12000ms 12000000ns 12000
label:[LABEL_KEY]

トレースには、完全に一致する指定されたラベルキーが含まれている必要があります。ラベルの値が指定されていても、その値は影響しません。次に例を示します。

label:/http/url
[LABEL_KEY]:[VALUE_PREFIX]

トレースには完全に一致する指定されたラベルキーが含まれている必要があり、ラベルの値は [VALUE_PREFIX] で始まる必要があります。たとえば、次のキーワードは、App Engine のバージョンが "2017" で始まるトレースと一致します。

g.co/gae/app/module_version:2017
+[LABEL_KEY]:[VALUE]

トレースには、完全に一致する指定されたラベルキーと値が含まれている必要があります。 例:

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[VALUE_PREFIX]

この構文は、ラベルテスト /http/method:[VALUE_PREFIX] の省略形です。

+method:[VALUE]

この構文は、ラベルテスト +/http/method:[VALUE] の省略形です。

url:[VALUE_PREFIX]

この構文は、ラベルテスト /http/url:[VALUE_PREFIX] の省略形です。

+url:[VALUE]

この構文は、ラベルテスト +/http/url:[VALUE] の省略形です。

ブール値の属性

ブール属性の値を指定するには、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 (\\)"

検索キーワードをルートスパンのみに限定するには、(^)を検索キーワードの前、ただしオプションの(+)がある場合はその後に追加します。[トレースリスト] ページの [フィルタ] フィールドでは、アノテーション +^ を追加すると、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 つが結果を返さない場合、それが原因と考えられます。