Cloud Trace 过滤条件

您可以使用跟踪记录过滤条件从 Cloud Trace 中选择一组跟踪记录。可以通过以下方式之一使用跟踪记录过滤条件:

  • 使用 list API 方法作为查询中的过滤条件参数。

  • 创建分析报告时作为请求过滤条件参数。

  • 作为轨迹浏览器页面中的过滤条件 字段。要了解如何创建和修改这些过滤条件,请参阅 显示最近的跟踪活动

使用过滤条件,您可以指定显示跟踪记录必须满足的一个或多个条件。通过过滤条件语法,您可以定义匹配是完全匹配还是前缀测试匹配。所有匹配项都区分大小写。

过滤条件概览

跟踪记录过滤条件由一个名为条件的比较序列组成。跟踪记录必须与过滤器中的所有条件匹配才能被选中。例如,以下过滤条件匹配的跟踪记录具有等于或大于一秒的延迟,并且包含一个名为 /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] 开头。

下表列出了 Cloud Trace 中使用过滤条件的语法:

分析报告页面中的 Trace API
请求过滤条件
Trace Explorer 页面中的过滤
root:[NAME_PREFIX] RootSpan:[NAME_PREFIX]
+root:[NAME_EXACT] RootSpan:+[NAME_EXACT]
span:[NAME_PREFIX] SpanName:[NAME_PREFIX]
+span:[NAME_EXACT] SpanName:+[NAME_EXACT]
[NAME_PREFIX] RootSpan:[NAME_PREFIX]
label:[LABEL_KEY] HasLabel:[LABEL_KEY]
[LABEL_KEY]:[VALUE_PREFIX] [LABEL_KEY]:[VALUE_PREFIX]*
+[LABEL_KEY]:[VALUE_EXACT] [LABEL_KEY]:+[VALUE]*
^[LABEL_KEY]:[VALUE_PREFIX] [LABEL_KEY]:^[VALUE_PREFIX]*
+^[LABEL_KEY]:[VALUE_EXACT] [LABEL_KEY]:^+[VALUE_EXACT]*, †
method:[VALUE_PREFIX] Method:[VALUE_PREFIX]
latency:10ms MinLatency:10ms
url:[VALUE_PREFIX] URL:[VALUE_PREFIX]

* 请勿将以下 Trace 关键字用作标签键:rootspanlabelmethodlatencyurl。无法查询具有这些标签键的跟踪记录。
Trace Explorer 页面中, 当您按 Enter 键后,注解 +^ 将转换为 ^+

本页面的其余部分将介绍使用 Trace API 时的过滤条件说明,以及分析报告页面上的请求过滤条件的说明。如果您在 Trace 探索器页面,然后在 以创建等效表达式。

请求过滤条件示例

以下介绍了过滤条件:

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,这与任何跟踪记录都不匹配。

  • 如需一次测试一个过滤条件字词,请使用“跟踪记录列表”过滤条件或 API Explorer。如果其中一个字词没有返回任何结果,那么问题可能就是该字词引起的。