このページは Cloud Translation API によって翻訳されました。

Cloud Trace フィルタ

このドキュメントでは、Cloud Trace API の list メソッドを使用するときにフィルタを構成する方法について説明します。フィルタを使用すると、トレースが返されるために満たす必要がある 1 つ以上の条件を指定できます。

このページは [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] で始める必要があることを意味します。

このページの残りの部分では、Cloud 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]

トレースには、全体で [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 メソッドに移動し、API Explorer を使用します。キーワードのうちの 1 つが結果を返さない場合、そのキーワードがデータが返されない原因である可能性があります。

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