Trace Filters

You can use trace filters to select a set of traces from Stackdriver Trace. Trace filters can be used in the projects.traces.list API method and in the Request text box on the Trace List page:

Go to the Trace List page

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 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].

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 mehtod:GET, the filter will be interpreted as label:mehtod: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.

Send feedback about...

Stackdriver Trace Documentation