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 projects.traces.list API method.

  • In the current UI, as the Request filter parameter when you use the Trace console to display a list of traces or to create an analysis report.

  • In the beta UI, as the Filter field when you use the Trace console to display a list of traces:

In the current Trace list window, the Request filter field lets 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.

In the beta Trace list window, you can also add filters that must must be satisfied for a trace to be displayed. However, with the beta, you you select filters from menus. For example, to add a filter, you click Add trace filter, select the type of filter from the menu, and then complete the value of the filter. You can enter the value, use the menu provided, or use a combination of approaches. For more information, see Filters.

The following table lists the names used in the Request filter bar and those used in the new menu-driven beta UI:

Name in filter bar (current) Name on menu (beta)
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 menu-driven filter implementation, if you add the annotation +^, it is converted to ^+ when you press Enter.

The remainder of this page describes the samples here use the current filter names. However, by using the mapping in previous table, the content is equally applicable to the beta UI.

Filter syntax

In the current UI, 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 will match 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 is a shortcut for root:[NAME_PREFIX].

+[NAME]

This 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, milliseconds is assumed. 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 is a shortcut for the label test, /http/method:[VALUE_PREFIX].

+method:[VALUE]

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

url:[VALUE_PREFIX]

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

+url:[VALUE]

This 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 (\\)"

In the current Trace list window, adding a (^) before a search term and after the optional (+) restricts the search term to only the root span. In the beta Trace list window, 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

will match traces whose root span's label /http/url has "/main" as the exact value, root span's name has /images as the prefix value and any span has label /http/method set to 200

Troubleshooting

Slow performance

If your trace filter is complicated, it will take 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 will be interpreted as label:method:GET, which does not match any traces.

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