[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-19。"],[],[],null,["# Cloud Trace filters\n\nThis document describes how you can configure filters when you use the\nCloud Trace API [`list`](/trace/docs/reference/v1/rest/v1/projects.traces/list) method.\nFilters let you specify one or more conditions that must be\nsatisfied for a trace to be returned.\n\nThe page doesn't apply to the\n**Trace Explorer** page. To filter the data shown on that page,\neither use the predefined filters, which are listed in the\n**Span filters** pane, or use the **Filter** bar.\nFor more information, see [Find and explore traces](/trace/docs/finding-traces).\n\nFilter overview\n---------------\n\nTrace filters consist of a sequence of\ncomparisons called **terms** . Traces must\nmatch all the terms in the filter to be selected. For example, the following\nfilter matches traces that have a latency of one second or more, and that\ncontain a span named `/modules.GetNumInstances`: \n\n +span:/modules.GetNumInstances latency:1s\n\nAll string comparisons are case-sensitive.\n\n### Boolean attributes\n\nTo specify values for Boolean attributes, use `false` for false, and `true`\nfor true: \n\n Client:true\n\n### Special characters\n\nSimple values, that is those that match the regular expression\n`[a-zA-Z0-9./_][a-zA-Z0-9./_-]*`, can be provided without quotation: \n\n environment:production\n path:/index.html\n error_code:200\n\nValues that include other characters, including whitespace, must be enclosed in\ndouble-quote (`\"`) characters: \n\n my-label:\"Notice: This value contains spaces and a colon\"\n\nTo search for the double-quote character or the backslash\n(`\\`) character within\na quoted string, escape the character with a backslash: \n\n my-label:\"Notice: This value contains spaces, a colon, a \\\"quote\\\", and a backslash (\\\\)\"\n\nFilter syntax\n-------------\n\nOn this page, `NAME` refers to the name\nof a field while `VALUE` refers to the value of a key-value pair. The strings\n`_PREFIX` and `_EXACT` are visual indications of whether a test is a\nprefix-test or an exact match. For example, `root:[NAME_PREFIX]` means\nthat the name of the root span must begin with `[NAME_PREFIX]`.\n| **Note:** Don't use the following keywords as label keys: `root`, `span`, `label`, `method`, `latency`, and `url`. Traces with these label keys can't be queried.\n\nThe remainder of this page contains a description for filters when using\nCloud Trace API.\n\n### Request filter examples\n\nThe following describes the filter terms:\n\n`root:[NAME_PREFIX]`\n\n: The trace's root-span name must begin with \\[NAME_PREFIX\\]. For example, the\n following filter matches a trace named `\"/_ah/background\"`, but not one\n named `\"/_ahx/background\"`:\n\n root:/_ah/\n\n`+root:[NAME]`\n\n: The trace's root-span name must be \\[NAME\\], exactly. For example:\n\n +root:/_ah/background\n\n`[NAME_PREFIX]`\n\n: This syntax is a shortcut for `root:[NAME_PREFIX]`.\n\n`+[NAME]`\n\n: This syntax is a shortcut for `+root:[NAME]`.\n\n`span:[NAME_PREFIX]`\n\n: The trace must have at least one span whose name begins with \\[NAME_PREFIX\\].\n For example:\n\n span:/modules.\n\n`+span:[NAME]`\n\n: The trace must have at least one span whose name is \\[NAME\\], exactly. For\n example,\n\n span:/modules.GetNumInstances\n\n`latency:[DURATION]`\n\n: The trace must have an overall latency that is greater or equal to\n \\[DURATION\\]. The duration is expressed as an integer followed by a units\n specifier: `s` for seconds, `ms` for milliseconds, or `ns` for nanoseconds.\n If there is no unit specifier, then the units are milliseconds. For\n example, the following four durations are the same:\n\n 12s 12000ms 12000000ns 12000\n\n`label:[LABEL_KEY]`\n\n: The trace must contain the specified label key, exactly. The value of the\n label (if any) doesn't matter. For example,\n\n label:/http/url\n\n`[LABEL_KEY]:[VALUE_PREFIX]`\n\n: The trace must contain the specified label key, exactly, and the value of\n the label must start with \\[VALUE_PREFIX\\]. For example, the following term\n matches traces whose App Engine version begins with `\"2017\"`.\n\n g.co/gae/app/module_version:2017\n\n`+[LABEL_KEY]:[VALUE_EXACT]`\n\n: The trace must contain the specified label key *and* value, exactly.\n For example,\n\n +g.co/gae/app/module_version:201750925t173233.387410594824284458\n\n`method:[VALUE_PREFIX]`\n\n: This syntax is a shortcut for the label test, `/http/method:[VALUE_PREFIX]`.\n\n`+method:[VALUE_EXACT]`\n\n: This syntax is a shortcut for the label test, `+/http/method:[VALUE_EXACT]`.\n\n`url:[VALUE_PREFIX]`\n\n: This syntax is a shortcut for label test, `/http/url:[VALUE_PREFIX]`.\n\n`+url:[VALUE_EXACT]`\n\n: This syntax is a shortcut for label test, `+/http/url:[VALUE_EXACT]`.\n\n### Root-span search examples\n\nTo restrict the search term to only the root span, add a (`^`) before a\nsearch term and after the optional (`+`).\nFor the **Filter** field in the **Trace Explorer** page, if you add the\nannotation `+^`, it is converted to `^+` when you press **Enter**.\n\nThe following show some root-span-only search terms and their equivalences:\n\n`^label:[LABEL_KEY]`\n: This is a root-span search for `label:[LABEL_KEY]`.\n\n`^[LABEL_KEY]:[VALUE_PREFIX]`\n: This is a root-span search for `[LABEL_KEY]:[VALUE_PREFIX]`.\n\n`+^[LABEL_KEY]:[VALUE]`\n: This is a root-span search for `+[LABEL_KEY]:[VALUE]`.\n\n`^method:[VALUE_PREFIX]`\n: This is a root-span search for `method:[VALUE_PREFIX]`.\n\n`+^method:[VALUE]`\n: This is a root-span search for `+method:[VALUE]`.\n\n`^url:[VALUE_PREFIX]`\n: This is a root-span search for `url:[VALUE_PREFIX]`.\n\n`+^url:[VALUE]`\n: This is a root-span search for `+url:[VALUE]`.\n\n`^span:[NAME_PREFIX]`\n: This is equivalent to `root:[NAME_PREFIX]`.\n\n`+^span:[NAME]`\n: This is equivalent to `+root:[NAME]`.\n\nBy creating a query with mixed terms, the search can be further customized.\nFor example, \n\n +^url:/main /images method:200\n\nmatches traces when the root span label `/http/url` is exactly \"/main\",\nthe root span's name is prefixed by `/images`, and any span has the\nlabel `/http/method` with a value of 200.\n\nTroubleshooting\n---------------\n\nThis section contains troubleshooting content.\n\n### Slow performance\n\nIf your trace filter is complicated, it takes longer to run and could time\nout. To improve performance, simplify the filter.\n\n### No results\n\nIf your filter does not return any traces, check the following:\n\n- Be sure there are no spaces in the filter except the ones that\n separate the comparisons.\n\n- Be sure the letter case and spelling of all the words in the filter is\n correct. For example, if you misspell a keyword such as `method:GET`, the\n filter is interpreted as `label:method:GET`, which does not match any\n traces.\n\n- To test the filter terms one at a time, go to the\n [`list`](/trace/docs/reference/v1/rest/v1/projects.traces/list) API method and then use the\n APIs Explorer. If one of the terms returns no results, then that term\n might be the reason why no data is being returned.\n\n The APIs Explorer is open when the page displays a pane titled,\n **Try this method** . If necessary, click **Try it**, which opens the\n APIs Explorer."]]
