Cloud Trace 过滤条件

借助 Cloud Trace 过滤条件，您可以查询 Trace API list 方法，以仅检索符合特定条件的跟踪记录，例如 span 名称、最低延迟时间、HTTP 属性或标签。

这些过滤表达式不适用于 Google Cloud 控制台中的 Trace 探索器页面。在 Trace 探索器中，您可以使用 span 过滤条件窗格中的预定义过滤条件或使用过滤条件栏来过滤轨迹。如需了解详情，请参阅查找和探索轨迹。

过滤条件概览

跟踪记录过滤条件由一个名为条件的比较序列组成。跟踪记录必须与过滤器中的所有条件匹配才能被选中。例如，以下过滤条件会匹配延迟时间为 1 秒或更长且包含名为 /modules.GetNumInstances 的 span 的轨迹：

+span:/modules.GetNumInstances latency:1s

所有字符串比较都区分大小写。

布尔值属性

如需为布尔属性指定值，请使用 false 表示 false，使用 true 表示 true：

Client:true

特殊字符

简单值（即与正则表达式 [a-zA-Z0-9./_][a-zA-Z0-9./_-]* 匹配的值）可以不加引号：

environment:production
path:/index.html
error_code:200

包含其他字符（包括空格）的值必须用双引号 (") 括起来：

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

如需在带英文引号的字符串中搜索英文双引号字符或反斜杠 (\) 字符，请使用反斜杠对该字符进行转义：

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

过滤器语法

在本页中，NAME 是指字段名称，而 VALUE 是指键值对的值。字符串 _PREFIX 和 _EXACT 是用于指示测试是前缀测试还是完全匹配的直观指示。例如，root:[NAME_PREFIX] 表示根 span 的名称必须以 [NAME_PREFIX] 开头。

注意： 请勿将以下关键字用作标签键：root、span、label、method、latency 和 url。无法查询具有这些标签键的轨迹。

本页的其余部分介绍了 Trace API 的过滤条件语法。

请求过滤条件示例

以下列表介绍了过滤条件：

root:[NAME_PREFIX]

跟踪记录的根 span 名称必须以 [NAME_PREFIX] 开头。例如，以下过滤条件匹配名为 "/_ah/background" 的跟踪记录，但不匹配名为 "/_ahx/background" 的跟踪记录：

root:/_ah/

+root:[NAME]

跟踪记录的根 span 名称必须与 [NAME] 完全一致。例如：

+root:/_ah/background

[NAME_PREFIX]

此语法是 root:[NAME_PREFIX] 的快捷方式。

+[NAME]

此语法是 +root:[NAME] 的快捷方式。

span:[NAME_PREFIX]

跟踪记录必须至少有一个名称以 [NAME_PREFIX] 开头的 span。例如：

span:/modules.

+span:[NAME]

跟踪记录必须至少有一个名称与 [NAME] 完全一致的 span。例如：

+span:/modules.GetNumInstances

latency:[DURATION]

轨迹必须具有大于或等于 [持续时间] 的总体延迟时间。时长以整数表示，后跟单位说明符：s 表示秒，ms 表示毫秒，ns 表示纳秒。如果没有单位说明符，则单位为毫秒。例如，以下四种时长是相同的：

12s 12000ms 12000000ns 12000

label:[LABEL_KEY]

跟踪记录必须确切地包含指定的标签键。标签值（如有）则无关紧要。例如：

label:/http/url

[LABEL_KEY]:[VALUE_PREFIX]

跟踪记录必须确切地包含指定的标签键，标签值必须以 [VALUE_PREFIX] 开头。例如，以下字词匹配 App Engine 版本以 "2017" 开头的轨迹：

g.co/gae/app/module_version:2017

+[LABEL_KEY]:[VALUE_EXACT]

跟踪记录必须确切地包含指定的标签键和值。例如：

+g.co/gae/app/module_version:201750925t173233.387410594824284458

method:[VALUE_PREFIX]

此语法是标签测试 /http/method:[VALUE_PREFIX] 的快捷方式。

+method:[VALUE_EXACT]

此语法是标签测试 +/http/method:[VALUE_EXACT] 的快捷方式。

url:[VALUE_PREFIX]

此语法是标签测试 /http/url:[VALUE_PREFIX] 的快捷方式。

+url:[VALUE_EXACT]

此语法是标签测试 +/http/url:[VALUE_EXACT] 的快捷方式。

根 span 搜索示例

如需将搜索字词限制为仅限根 span，请在搜索字词之前添加尖号 (^)，并在可选的加号 (+) 之后添加尖号。对于轨迹浏览器页面中的过滤条件字段，如果您添加注解 +^，则在按 Enter 键时，该注解会转换为 ^+。

以下列表显示了一些仅限根 span 的搜索字词及其等效字词：

^label:[LABEL_KEY]

表示在根 span 中搜索 label:[LABEL_KEY]。

^[LABEL_KEY]:[VALUE_PREFIX]

表示在根 span 中搜索 [LABEL_KEY]:[VALUE_PREFIX]。

+^[LABEL_KEY]:[VALUE]

表示在根 span 中搜索 +[LABEL_KEY]:[VALUE]。

^method:[VALUE_PREFIX]

表示在根 span 中搜索 method:[VALUE_PREFIX]。

+^method:[VALUE]

表示在根 span 中搜索 +method:[VALUE]。

^url:[VALUE_PREFIX]

表示在根 span 中搜索 url:[VALUE_PREFIX]。

+^url:[VALUE]

表示在根 span 中搜索 +url:[VALUE]。

^span:[NAME_PREFIX]

这等同于 root:[NAME_PREFIX]。

+^span:[NAME]

这等同于 +root:[NAME]。

您还可以通过创建包含混合字词的查询来进一步自定义搜索。 例如，

+^url:/main /images method:200

当根 span 标签 /http/url 正好为“/main”、根 span 的名称以 /images 为前缀，并且任何 span 具有标签 /http/method 且值为 200 时，匹配轨迹。

问题排查

以下部分介绍了如何解决与轨迹过滤器相关的常见问题。

性能下降

如果您的轨迹过滤条件很复杂，则运行时间会更长，并且可能会超时。如需提升性能，请简化过滤条件。

无结果

如果您的过滤条件未返回任何轨迹，请检查以下各项：

• 确保过滤器中除了分隔比较的空格没有其他空格。

• 请确保过滤条件中所有字词的大小写和拼写均正确无误。例如，如果您拼错关键字（例如 method:GET），则过滤条件会被解读为 label:method:GET，而这与任何轨迹都不匹配。

• 如需逐个测试过滤条件，请前往 list API 方法，然后使用 APIs Explorer。如果某个搜索字词未返回任何结果，则该字词可能是未返回任何数据的原因。

  当页面显示标题为试用此方法的窗格时，表示 APIs Explorer 已打开。如有必要，请点击试试看，这会打开 APIs Explorer。