Cloud Trace フィルタ

Cloud Trace フィルタを使用すると、Trace API の list メソッドをクエリして、スパン名、最小レイテンシ、HTTP 属性、ラベルなどの特定の条件に一致するトレースのみを取得できます。

これらのフィルタ式は、 Google Cloud コンソールの [Trace エクスプローラ] ページには適用されません。トレース エクスプローラでは、[スパンフィルタ] ペインの事前定義されたフィルタを使用するか、[フィルタ] バーを使用してトレースをフィルタできます。詳細については、トレースを検索して調査するをご覧ください。

フィルタの概要

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

+span:/modules.GetNumInstances latency:1s

文字列の比較では大文字と小文字が区別されます。

ブール値の属性

ブール値の属性の値を指定するには、false には false、true には true を使用します。

Client:true

特殊文字

正規表現 [a-zA-Z0-9./_][a-zA-Z0-9./_-]* に一致する単純な値は、引用符なしで指定できます。

environment:production
path:/index.html
error_code:200

空白文字などの他の文字を含む値は、二重引用符（"）で囲む必要があります。

my-label:"Notice: This value contains spaces and a colon"

引用符で囲まれた文字列内の二重引用符文字またはバックスラッシュ（\）文字を検索するには、バックスラッシュで文字をエスケープします。

my-label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

フィルタの構文

このページでは、NAME はフィールドの名前を指し、VALUE は Key-Value ペアの値を指します。文字列 _PREFIX と _EXACT は、テストがプレフィックス テストか完全一致かを示す視覚的な表示です。たとえば、root:[NAME_PREFIX] は、ルートスパンの名前を [NAME_PREFIX] で始める必要があることを意味します。

このページの残りの部分では、Trace API のフィルタ構文について説明します。

リクエスト フィルタの例

以下では、フィルタ キーワードについて説明します。

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]

トレースの全体的なレイテンシは [期間] 以上でなければなりません。期間は、整数の後に単位指定子（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_EXACT]

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

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[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 つずつテストするには、list API メソッドに移動して、APIs Explorer を使用します。いずれかの用語で結果が返されない場合は、その用語がデータが返されない原因である可能性があります。

    [このメソッドを試す] というタイトルのペインがページに表示されている場合、API Explorer は開いています。必要に応じて、[試してみる] をクリックします。API Explorer が開きます。