Cloud Trace 过滤条件

本文档介绍了在使用 Cloud Trace API list 方法或创建分析报告时如何配置过滤条件。使用过滤条件，您可以指定返回跟踪记录必须满足的一个或多个条件。

此页面不适用于轨迹浏览器页面。如需过滤该页面上显示的数据，请使用范围过滤条件窗格中列出的预定义过滤条件，或使用过滤条件栏。如需了解详情，请参阅查找和探索跟踪记录。

过滤条件概览

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

+span:/modules.GetNumInstances latency:1s

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

布尔值属性

要指定布尔值属性的值，请将 0 用于 false，将 1 用于 true。例如：

Client:0

特殊字符

如需搜索包含空格或冒号 (:) 字符的值，请用双引号 (") 字符将值引起来。例如：

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

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

    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。无法查询具有这些标签键的轨迹。

本页面的其余部分将介绍使用 Cloud 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]

跟踪记录的总延迟必须大于或等于 [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 方法，然后使用 API Explorer。如果其中一个字词没有返回任何结果，那么该字词可能就是没有返回任何数据的原因。

  当页面显示标题为试用此方法的窗格时，表示 API Explorer 已打开。如有必要，请点击试用，以打开 API 浏览器。