Cloud Trace filters

This document describes how you can configure filters when you use theCloud Trace APIlist method.Filters let you specify one or more conditions that must besatisfied for a trace to be returned.

The page doesn't apply to theTrace Explorer page. To filter the data shown on that page,either use the predefined filters, which are listed in theSpan filters pane, or use theFilter bar.For more information, seeFind and explore traces.

Filter overview

Trace filters consist of a sequence ofcomparisons calledterms. Traces mustmatch all the terms in the filter to be selected. For example, the followingfilter matches traces that have a latency of one second or more, and thatcontain a span named/modules.GetNumInstances:

+span:/modules.GetNumInstances latency:1s

All string comparisons are case-sensitive.

Boolean attributes

To specify values for Boolean attributes, usefalse for false, andtruefor true:

Client:true

Special characters

Simple values, that is those that match the regular expression[a-zA-Z0-9./_][a-zA-Z0-9./_-]*, can be provided without quotation:

environment:productionpath:/index.htmlerror_code:200

Values that include other characters, including whitespace, must be enclosed indouble-quote (") characters:

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

To search for the double-quote character or the backslash(\) character withina quoted string, escape the character with a backslash:

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

Filter syntax

On this page,NAME refers to the nameof a field whileVALUE refers to the value of a key-value pair. The strings_PREFIX and_EXACT are visual indications of whether a test is aprefix-test or an exact match. For example,root:[NAME_PREFIX] meansthat the name of the root span must begin with[NAME_PREFIX].

Note: Don't use the following keywords as label keys:root,span,label,method,latency, andurl. Traces with theselabel keys can't be queried.

The remainder of this page contains a description for filters when usingCloud Trace API.

Request filter examples

The following describes the filter terms:

root:[NAME_PREFIX]

The trace's root-span name must begin with [NAME_PREFIX]. For example, thefollowing filter matches a trace named"/_ah/background", but not onenamed"/_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 forroot:[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. Forexample,

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, orns 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 thelabel (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 ofthe label must start with [VALUE_PREFIX]. For example, the following termmatches traces whose App Engine version begins with"2017".

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

The trace must contain the specified label keyand 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_EXACT]

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

url:[VALUE_PREFIX]

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

+url:[VALUE_EXACT]

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

Root-span search examples

To restrict the search term to only the root span, add a (^) before asearch term and after the optional (+).For theFilter field in theTrace Explorer page, if you add theannotation+^, it is converted to^+ when you pressEnter.

The following show some root-span-only search terms and their equivalences:

^label:[LABEL_KEY]
This is a root-span search forlabel:[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 formethod:[VALUE_PREFIX].
+^method:[VALUE]
This is a root-span search for+method:[VALUE].
^url:[VALUE_PREFIX]
This is a root-span search forurl:[VALUE_PREFIX].
+^url:[VALUE]
This is a root-span search for+url:[VALUE].
^span:[NAME_PREFIX]
This is equivalent toroot:[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 thelabel/http/method with a value of 200.

Troubleshooting

This section contains troubleshooting content.

Slow performance

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

No results

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.