Cloud Trace filters

You use trace filters to select a set of traces from Cloud Trace. Use a trace filter in one of the following ways:

  • As the filter parameter in a query using the list API method.

  • As the Request filter parameter when you create an analysis report..

  • As the Filter field in the Trace list page. For information on creating and modifying these filters, see Filters.

Filters let you specify one or more conditions that must be satisfied for a trace to be displayed. The filter syntax lets you define when matches are exact, or when they are prefix tests. All matches are case-sensitive.

The following table lists the syntax used filters in Cloud Trace:

Trace API
Request Filter in the Analysis Reports page
Filter in the Trace List page
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]

* In the Trace List page, the annotation +^, it is converted to ^+ when you press Enter.

The remainder of this page contains a description for filters when using Trace API and for the Request Filter on the Analysis Reports page. If you are using the Filter field in the Trace list page, then you can use the mapping in the previous table to create an equivalent expression.

Filter syntax

Trace filters consist of a sequence of comparisons called terms. Traces must match all the terms in the filter to be selected. For example, the following filter matches traces that have a latency of one second or more, and that contain a span named /modules.GetNumInstances:

+span:/modules.GetNumInstances latency:1s

All string comparisons are case-sensitive. The filter terms are listed below:

root:[NAME_PREFIX]

The trace's root-span name must begin with [NAME_PREFIX]. For example, the following filter matches a trace named "/_ah/background", but not one named "/_ahx/background":

root:/_ah/
+root:[NAME]

The trace's root-span name must be [NAME], exactly. For example:

+root:/_ah/background
[NAME_PREFIX]

This syntax is a shortcut for root:[NAME_PREFIX].

+[NAME]

This syntax is a shortcut for +root:[NAME].

span:[NAME_PREFIX]

The trace must have at least one span whose name begins with [NAME_PREFIX]. For example:

span:/modules.
+span:[NAME]

The trace must have at least one span whose name is [NAME], exactly. For example,

span:/modules.GetNumInstances
latency:[DURATION]

The trace must have an overall latency that is greater or equal to [DURATION]. The duration is expressed as an integer followed by a units specifier: s for seconds, ms for milliseconds, or ns for nanoseconds. If there is no unit specifier, then the units are milliseconds. For example, the following four durations are the same:

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

The trace must contain the specified label key, exactly. The value of the label (if any) doesn't matter. For example,

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

The trace must contain the specified label key, exactly, and the value of the label must start with [VALUE_PREFIX]. For example, the following term matches traces whose App Engine version begins with "2017".

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

The trace must contain the specified label key and value, exactly. For example,

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

This syntax is a shortcut for the label test, /http/method:[VALUE_PREFIX].

+method:[VALUE]

This syntax is a shortcut for the label test, +/http/method:[VALUE].

url:[VALUE_PREFIX]

This syntax is a shortcut for label test, /http/url:[VALUE_PREFIX].

+url:[VALUE]

This syntax is a shortcut for label test, +/http/url:[VALUE].

Boolean attributes

To specify values for Boolean attributes, use 0 for false, and 1 for true. For example,

Client:0

Special characters

To search for a value that contains whitespace or the colon (:) character, enclose the value in double-quote (") characters. For example,

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

To search for the double-quote character or the backslash (\) character within a quoted string, escape the character with a backslash. For example,

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

To restrict the search term to only the root span, add a (^) before a search term and after the optional (+). For the Filter field in the Trace list page, if you add the annotation +^, it is converted to ^+ when you press Enter.

Below are some root-span-only search terms and their equivalences:

^label:[LABEL_KEY]
This is a root-span search for label:[LABEL_KEY].
^[LABEL_KEY]:[VALUE_PREFIX]
This is a root-span search for [LABEL_KEY]:[VALUE_PREFIX].
+^[LABEL_KEY]:[VALUE]
This is a root-span search for +[LABEL_KEY]:[VALUE].
^method:[VALUE_PREFIX]
This is a root-span search for method:[VALUE_PREFIX].
+^method:[VALUE]
This is a root-span search for +method:[VALUE].
^url:[VALUE_PREFIX]
This is a root-span search for url:[VALUE_PREFIX].
+^url:[VALUE]
This is a root-span search for +url:[VALUE].
^span:[NAME_PREFIX]
This is equivalent to root:[NAME_PREFIX].
+^span:[NAME]
This is equivalent to +root:[NAME].

By creating a query with mixed terms, the search can be further customized. For example,

    +^url:/main /images method:200

matches traces when the root span label /http/url is exactly "/main", the root span's name is prefixed by /images, and any span has the label /http/method with a value of 200.

Troubleshooting

Slow performance

If your trace filter is complicated, it takes longer to run and could time out. To improve performance, simplify the filter.

No results

If your filter does not return any traces, check the following:

  • Be sure there are no spaces in the filter except the ones that separate the comparisons.

  • Be sure the letter case and spelling of all the words in the filter is correct. For example, if you misspell a keyword such as method:GET, the filter is interpreted as label:method:GET, which does not match any traces.

  • To test the filter terms one at a time, use the Trace List filter or the APIs Explorer. If one of the terms returns no results, it might be the culprit.