使用筛选条件表达式在控制台中搜索跟踪 - AWS X-Ray
筛选条件表达式详细信息将筛选条件表达式与组一起使用筛选条件表达式语法布尔值关键字数字关键字字符串关键字复杂关键字id 功能
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

如果我们为英文版本指南提供翻译，那么如果存在任何冲突，将以英文版本指南为准。在提供翻译时使用机器翻译。

使用筛选条件表达式在控制台中搜索跟踪

当您选择某个跟踪时间段以在 X-Ray 控制台中查看时，您获得的结果可能会超出可在控制台中显示的内容。在右上角，控制台显示其扫描的跟踪数量，以及是否有更多跟踪可用。

您可以使用筛选条件表达式 缩小结果范围，以仅限于您要查找的跟踪。

筛选条件表达式详细信息

当您选择服务地图中的节点时，控制台会基于节点的服务名以及您的选择中提供的错误类型来构建筛选条件表达式。要查找显示性能问题的跟踪或与特定请求相关的跟踪，您可以调整控制台提供的表达式，或创建您自己的表达式。如果您使用 X-Ray 开发工具包添加注释，您还可以根据是否存在注释键或根据键值进行筛选。

注意

如果您在服务地图中选择相对时间范围并选择一个节点，则控制台会将时间范围转换为绝对开始和结束时间。为了确保节点的跟踪显示在搜索结果中，并避免扫描时间在该节点未处于活动状态的期间内，时间范围只应包含该节点发送跟踪的时间。若要相对于当前时间进行搜索，您可以在跟踪页面中切换回相对时间范围，并重新扫描。

如果结果仍超过控制台可显示的内容，控制台会显示有多少个跟踪匹配，以及扫描的跟踪数。显示的百分比是已扫描选定时间范围的百分比。为确保您会看到在结果中提供所有匹配的跟踪，进一步缩小筛选条件表达式的范围，或选择一个更短的时间范围。

为了先获取最新结果，控制台会从时间范围结尾开始反向扫描。如果有大量的跟踪，但结果很少，控制台会将时间范围分为多个分块并执行并行扫描。进度条显示已扫描的时间范围部分。

将筛选条件表达式与组一起使用

组是由筛选条件表达式定义的跟踪的集合。您可以使用组生成其他服务图并提供 Amazon CloudWatch 指标。

组由其名称或 Amazon 资源名称 (ARN) 标识，并包含筛选条件表达式。此服务将比较传入到表达式的跟踪并相应地存储它们。

您可以使用筛选条件表达式搜索栏左侧的下拉菜单创建和修改组。

注意

如果服务在限定组时遇到错误，则在处理传入跟踪时不再包含该组，并记录错误指标。

有关组的更多信息,请参阅 在中配置组 X-Ray 控制台.

筛选条件表达式语法

筛选条件表达式可以包含一个关键字、一个一元或二元运算符 和一个值 用于比较。 

keyword operator value

不同的运算符可用于不同类型的关键字。例如，responsetime 是一个数字关键字，可与数字相关运算符进行比较。

例 – 响应时间超过 5 秒的请求

responsetime > 5

您可以使用 AND 或 OR 运算符将多个表达式组合成一个复合表达式。

例 – 总时长在 5–8 秒之间的请求

duration >= 5 AND duration <= 8

简单的关键字和运算符只在跟踪级别查找问题。如果下游发生了错误，但被您的应用程序处理了而未返回给用户，则搜索 error 将找不到它。

要查找存在下游问题的迹线,您可以使用 复杂关键字 service() 和 edge()。这些关键字允许您将筛选器表达式应用到所有下游节点、单个下游节点或两个节点之间的边缘。要想获得更细的粒度，您可以使用 id() 函数按类型筛选服务和边缘。

布尔值关键字

布尔关键字值可为 true 或 false。使用这些关键字查找导致错误的跟踪。

布尔值关键字

  • ok – 响应状态代码为 2XX，成功。

  • error – 响应状态代码为 4XX，客户端错误。

  • throttle – 响应状态代码为“429 请求过多”。

  • fault – 响应状态代码为 5XX，服务器错误。

  • partial – 请求包含未完成的分段。

  • inferred – 请求具有推断分段。

  • first – 元素是枚举列表中的第一个元素。

  • last – 元素是枚举列表中的最后一个元素。

  • remote – 根本原因实体是远程的。

  • root – 服务是跟踪的入口点或根分段。

布尔运算符查找指定键为 true 或 false 的分段。

布尔运算符

  • none – 如果关键字为 true，则表达式为 true。

  • ! – 如果关键字为 false，则表达式为 true。

  • =,!= – 将关键字的值与字符串进行比较 true 或 false。这些运算符的作用与其他运算符相同,但更明确。

例 – 响应状态为 2XX OK

ok

例 – 响应状态不为 2XX OK

!ok

例 – 响应状态不为 2XX OK

ok = false

例 – 上次枚举的错误跟踪具有错误名称“deserialize”

rootcause.fault.entity { last and name = "deserialize" }

例 – 包含远程分段的请求，其覆盖率大于 0.7 且服务名称为“traces”

rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }

例 – 具有推断分段（其中，服务类型为“AWS:DynamoDB”）的请求

rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }

例 – 将名称为“data-plane”的分段用作根的请求

service("data-plane") {root = true and fault = true}

数字关键字

使用数字关键字可以搜索具有特定响应时间、持续时间或响应状态的请求。

数字关键字

  • responsetime – 服务器发送响应所用的时间。

  • duration – 包括所有下游调用的请求总时长。

  • http.status – 响应（状态代码）。

  • index – 元素在枚举列表中的位置。

  • coverage – 实体响应时间占根分段响应时间的小数百分比。仅适用于响应时间根本原因实体。

数字运算符

数字关键字使用标准相等运算符和比较运算符。

  • =、!= – 关键字等于或不等于某个数值。

  • <、<=、>、>= – 关键字小于或大于某个数值。

例 – 响应状态不为 200 OK

http.status != 200

例 – 总时长在 5–8 秒之间的请求

duration >= 5 AND duration <= 8

例 – 在 3 秒内成功完成的请求，包括所有下游调用

ok !partial duration <3

例 – 索引大于 5 的枚举列表实体 

rootcause.fault.service { index > 5 }

例 – 其最后一个实体覆盖率大于 0.8 的请求

rootcause.responsetime.entity { last and coverage > 0.8 }

字符串关键字

使用字符串关键字可以查找请求标头中包含特定文本的跟踪，或查找特定用户 ID。

字符串关键字

  • http.url – 请求 URL。

  • http.method – 请求方法。

  • http.useragent – 请求的用户代理字符串。

  • http.clientip – 请求者 IP 地址。

  • user – 跟踪中任意分段的用户字段的值。

  • name – 服务或异常的名称。

  • type – 服务类型。

  • message – 异常消息。

  • availabilityzone – 跟踪中任意分段上可用区字段的值。

  • instance.id – 跟踪中任意分段上的实例 ID 字段的值。

  • resource.arn – 跟踪中任何分段上的资源 ARN 字段的值。

字符串运算符查找等于或包含特定文本的值。必须始终在引号中指定值。

字符串运算符

  • =、!= – 关键字等于或不等于某个数值。

  • CONTAINS – 关键字包含特定字符串。

  • BEGINSWITH、ENDSWITH – 关键字以特定字符串开头或结尾。

例 – http.url 筛选器

http.url CONTAINS "/api/game/"

要测试跟踪中是否存在某个字段而不考虑其值，可检查它是否包含空字符串。

例 – 用户筛选器

查找所有带有用户 ID 的跟踪。

user CONTAINS ""

例 – 选择跟踪，跟踪所具有的故障根本原因包含名为“Auth”的服务

rootcause.fault.service { name = "Auth" }

例 – 选择跟踪，跟踪所具有的响应时间根本原因的最后一个服务的类型为 DynamoDB 

rootcause.responsetime.service { last and type = "AWS::DynamoDB" }

例 – 选择故障根本原因为最后一个异常的跟踪,其中消息“访问拒绝用于account_id: 1234567890

rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"

复杂关键字

使用复杂关键字可根据服务名称、边缘节点名称或注释值查找请求。对于服务和边缘节点，您可以指定应用于服务或边缘节点的附加筛选条件表达式。对于注释，您可以使用布尔值、数字或字符串运算符筛选具有特定键的注释的值。

复杂关键字

  • annotation.key – 带字段的注释的值 key注释的值可以是布尔值、数字或字符串，因此您可以使用任意这些类型的比较运算符。此关键字不能与 service 或 edge 关键字组合使用。

  • edge(source, destination) {filter} – 服务之间的连接 source $and destination可选的大括号中可以包含应用于此连接上的分段的筛选条件表达式。

  • group.name / group.arn – 组筛选器表达式的值,按组名称或组ARN引用。

  • json – JSON 根本原因对象。有关以编程方式创建 JSON 实体的步骤，请参阅从 AWS X-Ray 获取数据。

  • service(name) {filter} – 服务名称 name可选的大括号中可以包含应用于服务所创建的分段的筛选条件表达式。

使用服务关键字查找命中服务地图上特定节点的请求的跟踪。

复杂关键字运算符查找已设置或未设置指定密钥的段。

复杂关键字运算符

  • 无 – 如果设置了关键字,表达式为true。如果关键字是布尔类型,它将对布尔值进行评估。

  • ! – 如果未设置关键字,表达式为true。如果关键字是布尔类型,它将对布尔值进行评估。

  • =,!= – 比较关键字的值。

  • edge(source, destination) {filter} – 服务之间的连接 source $and destination可选的大括号中可以包含应用于此连接上的分段的筛选条件表达式。

  • annotation.key – 带字段的注释的值 key注释的值可以是布尔值、数字或字符串，因此您可以使用任意这些类型的比较运算符。此关键字不能与 service 或 edge 关键字组合使用。

  • json – JSON 根本原因对象。有关以编程方式创建 JSON 实体的步骤，请参阅从 AWS X-Ray 获取数据。

使用服务关键字查找命中服务地图上特定节点的请求的跟踪。

例 – 服务筛选器

包括对 api.example.com 调用的请求出错 (500 系列错误)。 

service("api.example.com") { fault }

您可以排除服务名称，而将筛选条件表达式应用于服务地图上的所有节点。

例 – 服务筛选器

在服务地图上的任意位置导致 fault 的请求。

service() { fault }

边缘关键字将筛选条件表达式应用于两个节点之间的连接。

例 – 边缘筛选器

服务 api.example.com 对 backend.example.com 进行调用的请求因出现错误而失败。 

edge("api.example.com", "backend.example.com") { error }

您也可以将 ! 运算符与服务和边缘关键字结合使用来从另一个筛选条件表达式的结果中排除某个服务或边缘。

例 – 服务和请求筛选器

请求的 URL 以 http://api.example.com/ 开头且包含 /v2/，但并未到达名为 api.example.com 的服务。 

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")

例 – 服务和响应时间过滤器

查找迹线位置 http url 设置,响应时间大于2秒。 

http.url AND responseTime > 2

对于注释,您可以调用所有跟踪, annotation.key 或者使用与值的类型相对应的比较运算符。

例 – 带字符串值的注释

请求的注释名为 gameid，字符串值为 "817DL6VO"。 

annotation.gameid = "817DL6VO"

例 – 已设置注释

包含名为的注释的请求 age 设置。 

annotation.age

例 – 未设置注释

没有命名注释的请求 age 设置。 

!annotation.age

例 – 带数字值的注释

请求的注释期限数值大于 29。

annotation.age > 29

例 – 带用户的组

跟踪符合 high_response_time 组筛选器(例如。 responseTime > 3),并且用户命名为Alice。 

group.name = "high_response_time" AND user = "alice"

例 – 具有根本原因实体的 JSON

具有匹配的根本原因实体的请求。

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

id 功能

当您为 service 或 edge 关键字提供服务名称时，您将得到具有该名称的所有节点的结果。要进行更精确的筛选，可以使用 id 函数在名称之外再指定一个服务类型，以区分同名节点。 

id(name: "service-name", type:"service::type")

您可以在服务和边缘节点筛选条件中使用 id 函数来代替服务名称。 

service(id(name: "service-name", type:"service::type")) { filter }
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

例如, 刻痕样本应用 包括 AWS Lambda 函数命名 random-name。这将在服务映射中创建两个节点,一个用于函数调用,另一个用于 Lambda 服务。

两个节点的名称相同，但类型不同。标准服务筛选器将查找这两个节点的跟踪。

例 – 服务筛选器

在任何名为 random-name的服务上包含错误的请求。 

service("random-name") { error }

使用 id 函数将搜索范围缩小到函数本身的错误，排除服务的错误。

例 – 使用 id 函数的服务筛选器

名为 random-name、类型为 AWS::Lambda::Function 的服务中有错误的请求。 

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

要按类型搜索节点，您还可以完全排除名称。

例 – 使用 id 函数的服务筛选器

类型为 AWS::Lambda::Function 的服务中有错误的请求。 

service(id(type: "AWS::Lambda::Function")) { error }