Cloud Trace フィルタ

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

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

  • 現在のインターフェースでは、Trace コンソールを使用してトレースの一覧を表示したり、分析レポートを作成するときに、リクエスト フィルタパラメータとして使用します。

  • ベータ版のインターフェースでは、Trace コンソールを使用してトレースの一覧を表示するときの [フィルタ] フィールドとして使用します。

現在の [トレースリスト] ウィンドウで、[リクエスト フィルタ] フィールドを使用して、トレースを表示するために満たす必要がある 1 つ以上の条件を指定できます。フィルタ構文を使用すると、完全一致の場合または接頭辞テストの場合を定義できます。一致はすべて大文字と小文字が区別されます。

ベータ版の [トレースリスト] ウィンドウで、トレースを表示するのに満たされる必要のあるフィルタを追加することもできます。ただし、ベータ版ではメニューからフィルタを選択します。たとえば、フィルタを追加するには、[トレース フィルタを追加] をクリックし、メニューからフィルタのタイプを選択して、フィルタの値を入力します。値を入力する、メニューを使用する、または複数の方法を組み合わせて使用できます。詳細については、フィルタをご覧ください。

次のテーブルには、[リクエスト フィルタ] バーで使用される名前と、フィルタ メニューに表示される同等の名前が示されています。

フィルタバーの名前(現在) メニューの名前(ベータ版)
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] を押したときに ^+ に変換されます。

このページの残りの部分では、現在のフィルタ名を使用するサンプルについて説明します。ただし、前の表のマッピングを使用することで、コンテンツはベータ版インターフェースにも同様に適用できます。

フィルタの構文

現在のインターフェースでは、トレースフィルタはキーワードと呼ばれる一連の比較で構成されます。トレースは、選択するフィルタ内のすべてのキーワードと一致する必要があります。たとえば、次のフィルタは、レイテンシが 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 つが結果を返さない場合、それが原因と考えられます。