AWS X-Ray 分段文档 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS X-Ray 分段文档

跟踪分段是应用程序提供服务的请求的 JSON 表示形式。跟踪分段将记录有关原始请求的信息、有关应用程序本地执行的工作的信息以及子分段,而子分段包含有关应用程序向 AWS 资源、HTTP API 和 SQL 数据库发出的下游调用的信息。

分段文档将有关分段的信息传递给 X-Ray。分段文档最多可为 64 kB,并且包含一个带子分段的完整分段、指示请求正在进行中的分段部分或一个单独发送的子分段。您可以使用 PutTraceSegments API 将分段文档直接发送到 X-Ray。

X-Ray 将编译和处理分段文档以生成可查询的跟踪摘要完整跟踪,您可以分别使用 GetTraceSummariesBatchGetTraces API 访问二者。除了您发送到 X-Ray 的分段和子分段之外,服务还使用子分段中的信息生成推断的分段并将其添加到完整跟踪。推断的分段表示服务地图中的下游服务和资源。

X-Ray 提供分段文档的 JSON 架构。您可以在此处下载该架构:xray-segmentdocument-schema-v1.0.0。以下部分中更详细地描述了该架构中列出的字段和对象。

X-Ray 为分段字段的子集编制索引以用于筛选条件表达式。例如,如果您将分段上的 user 字段设置为唯一标识符,则可在 X-Ray 控制台中或使用 GetTraceSummaries API 搜索与特定用户关联的分段。有关更多信息,请参阅使用筛选条件表达式在控制台中搜索跟踪

在使用 X-Ray 开发工具包检测应用程序时,此开发工具包将为您生成分段文档。此开发工具包通过本地 UDP 端口将分段文档传输到 X-Ray 守护程序,而不是直接将分段文档发送到 X-Ray。有关更多信息,请参阅将分段文档发送到 X-Ray 守护程序

分段字段

分段记录有关应用程序提供服务的请求的跟踪信息。分段至少会记录请求的名称、ID、开始时间、跟踪 ID 和结束时间。

例 最小完成分段

{ "name" : "example.com", "id" : "70de5b6f19ff9a0a", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "end_time" : 1.478293361449E9 }

分段需要或有条件地需要以下字段。

注意

除非另行说明,否则值必须是字符串 (最多 250 个字符)。

必填分段字段

  • name – 处理了请求的服务的逻辑名称(最多 200 个字符)。例如,您的应用程序的名称或域名。名称可以包含 Unicode 字母、数字、空格和以下符号:_.:/%&#=+\-@

  • id – 分段的 64 位标识符,在同一个跟踪中的分段之间唯一,使用 16 位十六进制数

  • trace_id – 连接源自单个客户端请求的所有分段和子分段的唯一标识符。

    跟踪 ID 格式

    trace_id 由以连字符分隔的三组数字组成。例如:1-58406520-a006649127e371903a2de979。这包括:

    • 版本号,即 1

    • 原始请求的时间,采用 Unix 纪元时间,为 8 个十六进制数字

      例如,2016 年 12 月 1 日上午 10:00 (太平洋标准时间) 采用纪元时间为 1480615200,或者是十六进制数字 58406520

    • 跟踪的 96 位标识符,全局唯一,使用 24 个十六进制数字

    跟踪 ID 安全性

    跟踪 ID 在响应标头中可见。使用安全的随机算法生成跟踪 ID,确保攻击者无法计算未来的跟踪 ID 并使用这些 ID 向您的应用程序发送请求。

  • start_time – 表示分段的创建时间的数字,采用浮点秒数的纪元时间。例如,1480615200.0101.480615200010E9。使用所需数量的小数位。建议使用微秒解析 (如果可用)。

  • end_time – 表示分段的关闭时间的数字。例如,1480615200.0901.480615200090E9。指定 end_timein_progress

  • in_progress布尔值,设置为 true,而不是指定 end_time 以记录分段已经启动但未完成。在您的应用程序接收到需要长时间提供服务的请求时发送进行中的分段,用于跟踪请求接收。发送了响应之后,发送完成分段以覆盖进行中分段。仅为每个请求发送一个完整分段,以及一个或零个进行中分段。

服务名称

分段的 name 应与生成该分段的服务的域名或逻辑名相符。但这不是强制要求。任何拥有 PutTraceSegments 权限的应用程序均可以发送任何名称的分段。

以下字段是分段的可选字段。

可选分段字段

  • service – 一个包含应用程序的相关信息的对象。

    • version – 一个标识为请求提供服务的应用程序版本的字符串。

  • user – 一个标识发送请求的用户的字符串。

  • origin – 运行您的应用程序的 AWS 资源类型。

    支持的值

    • AWS::EC2::Instance – 一个 Amazon EC2 实例。

    • AWS::ECS::Container – 一个 Amazon ECS 容器。

    • AWS::ElasticBeanstalk::Environment – 一个 Elastic Beanstalk 环境。

    如果您的应用程序适用多个值,请使用最具体的值。例如,一个多容器 Docker Elastic Beanstalk 环境在一个 Amazon ECS容器上运行您的应用程序,该容器反过来又在 Amazon EC2 实例上运行。在这种情况下,您应将源设为 AWS::ElasticBeanstalk::Environment,因为环境是另外两种资源的父级。

  • parent_id – 您在请求源自分析过的应用程序时指定的子分段 ID。X-Ray 开发工具包将父级子分段 ID 添加到下游 HTTP 调用的跟踪标头。对于嵌套子分段,一个子分段可以有一个分段或一个子分段作为其父级。

  • httphttp 对象,包含原始 HTTP 请求的相关信息。

  • awsaws 对象,包含有关应用程序为请求提供服务的 AWS 资源的信息。

  • errorthrottlefaultcauseerror 字段,指示出现错误并且包含有关导致错误的异常的信息。

  • annotationsannotations 对象,包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。

  • metadatametadata 对象,包含要存储在分段中的任何附加数据。

  • subsegmentssubsegment 对象的数组

子分段

您可以创建子分段来记录您使用 AWS 开发工具包对 AWS 服务和资源发起的调用、对内部或外部 HTTP Web API 的调用或 SQL 数据库查询。您也可以创建子分段来调试应用程序中的代码块或为其添加注释。由于子分段可以包含其他子分段,因此,记录有关内部函数调用的元数据的自定义子分段可以包含其他自定义子分段和下游调用的子分段。

子分段从调用它的服务的视角记录下游调用。X-Ray 使用子分段来确定未发送分段的下游服务,并在服务图上为其创建条目。

子分段可以嵌入到完整分段文档或者单独发送。对于长时间运行的请求,单独发送子分段以异步跟踪下游调用,或者避免超过最大分段文档大小.

例 带有嵌入式子分段的分段

独立子分段具有 typesubsegment 以及标识父分段的 parent_id

{ "trace_id" : "1-5759e988-bd862e3fe1be46a994272793", "id" : "defdfd9912dc5a56", "start_time" : 1461096053.37518, "end_time" : 1461096053.4042, "name" : "www.example.com", "http" : { "request" : { "url" : "https://www.example.com/health", "method" : "GET", "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7", "client_ip" : "11.0.3.111" }, "response" : { "status" : 200, "content_length" : 86 } }, "subsegments" : [ { "id" : "53995c3f42cd8ad8", "name" : "api.example.com", "start_time" : 1461096053.37769, "end_time" : 1461096053.40379, "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } } } ] }

对于长时间运行的请求,您可以发送进行中分段来告知 X-Ray 已收到请求,然后在完成原始请求之前单独发送子分段来跟踪这些请求。

例 正在进行分段

{ "name" : "example.com", "id" : "70de5b6f19ff9a0b", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "in_progress": true }

例 独立子分段

独立子分段具有 typesubsegment,一个 trace_id 和一个标识父分段的 parent_id

{ "name" : "api.example.com", "id" : "53995c3f42cd8ad8", "start_time" : 1.478293361271E9, "end_time" : 1.478293361449E9, "type" : "subsegment", "trace_id" : "1-581cf771-a006649127e371903a2de979" "parent_id" : "defdfd9912dc5a56", "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } } }

在请求完成时,请使用 end_time 重新发送分段来关闭分段。完成分段将覆盖进行中分段。

您也可以为触发了异步工作流的已完成请求单独发送子分段。例如,在开始用户请求的工作之前,Web API 可能立即返回 OK 200 响应。您可以在发送响应后立即将完整分段发送到 X-Ray,然后为稍后完成的工作发送子分段。与分段一样,您还可以发送子分段片段来记录子分段已开始,然后在下游调用完成后用一个完整子分段覆盖此子分段。

子分段需要或有条件地需要以下字段。

注意

除非另行说明,否则值是字符串 (最多 250 个字符)。

必填子分段字段

  • id – 子分段的 64 位标识符,在同一个跟踪中的分段之间唯一,使用 16 位十六进制数

  • name – 子分段的逻辑名称。对于下游调用,命名调用的资源或服务后的子分段。对于自定义子分段,命名其检测的代码后的子分段 (例如,函数名称)。

  • start_time – 表示创建子分段的时间的数字,采用浮点秒数的纪元时间,精确到毫秒。例如,1480615200.0101.480615200010E9

  • end_time – 表示子分段的关闭时间的数字。例如,1480615200.0901.480615200090E9。指定 end_timein_progress

  • in_progress – 设置为 true布尔值,而不是指定 end_time 以记录子分段已经启动但未完成。仅为每个下游请求发送一个完整子分段,以及一个或零个进行中子分段。

  • trace_id – 子分段的父分段的跟踪 ID。仅在单独发送子分段时是必需的。

    跟踪 ID 格式

    trace_id 由以连字符分隔的三组数字组成。例如:1-58406520-a006649127e371903a2de979。这包括:

    • 版本号,即 1

    • 原始请求的时间,采用 Unix 纪元时间,为 8 个十六进制数字

      例如,2016 年 12 月 1 日上午 10:00 (太平洋标准时间) 采用纪元时间为 1480615200,或者是十六进制数字 58406520

    • 跟踪的 96 位标识符,全局唯一,使用 24 个十六进制数字

  • parent_id – 子分段的父分段的分段 ID。仅在单独发送子分段时是必需的。对于嵌套子分段,一个子分段可以有一个分段或一个子分段作为其父级。

  • typesubsegment。仅在单独发送子分段时是必需的。

以下字段是子分段的可选字段。

可选子分段字段

  • namespace – 对于 AWS 开发工具包调用,为 aws;对于其他下游调用,为 remote

  • httphttp 对象,包含有关传出 HTTP 调用的信息。

  • awsaws 对象,包含有关应用程序调用的下游 AWS 资源的信息。

  • errorthrottlefaultcauseerror 字段,指示出现错误并且包含有关导致错误的异常的信息。

  • annotationsannotations 对象,包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。

  • metadatametadata 对象,包含要存储在分段中的任何附加数据。

  • subsegments – subsegment 对象的数组

  • precursor_ids – 子分段 ID 的数组,标识在此子分段之前完成的具有相同父级的子分段。

HTTP 请求数据

使用 HTTP 数据块记录有关应用程序提供服务的 HTTP 请求 (在分段中) 或应用程序向下游 HTTP API 发出的 HTTP 请求 (在子分段中) 的详细信息。此对象中的大多数字段将映射到在 HTTP 请求和响应中找到的信息。

http

所有字段都是可选字段。

  • request – 有关请求的信息。

    • method – 请求方法。例如:GET

    • url – 从请求的协议、主机名和路径编译的完整请求 URL。

    • user_agent – 来自请求者客户端的用户代理字符串。

    • client_ip – 请求者的 IP 地址。可从 IP 数据包的 Source Address 或 (对于转发的请求) X-Forwarded-For 标头中检索。

    • x_forwarded_for –(仅分段)布尔值,指示已从 X-Forwarded-For 标头读取 client_ip,并且它不可靠,因为它可能是伪造的。

    • traced –(仅子分段)布尔值,指示下游调用针对的是另一个跟踪的服务。如果此字段设置为 true,则 X-Ray 会将跟踪视为已中断,直至下游服务上传一个分段,此分段的 id 与包含此数据块的子分段的 parent_id 匹配。

  • response – 有关响应的信息。

    • status – 指示响应的 HTTP 状态的数字

    • content_length – 指示响应正文长度(以字节为单位)的数字

在分析对下游 Web API 进行的调用时,记录包含有关 HTTP 请求和响应的信息的子分段。X-Ray 使用子分段为远程 API 生成推断分段。

例 由 Amazon EC2 上运行的应用程序提供服务的 HTTP 调用的分段

{ "id": "6b55dcc497934f1a", "start_time": 1484789387.126, "end_time": 1484789387.535, "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "2.4.0 for Java" }, }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } }

例 下游 HTTP 调用的子分段

{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } }

例 下游 HTTP 调用的推断分段

{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true }

注释

条件分段和子分段可包含一个 annotations 对象,此对象包含一个或多个字段,X-Ray 将为这些字段编制索引以便用于筛选表达式。字段可以包含字符串、数字或布尔值(无对象或数组)。X-Ray 最多为每个跟踪的 50 条注释编制索引。

例 带有注释的 HTTP 调用的分段

{ "id": "6b55dcc497932f1a", "start_time": 1484789187.126, "end_time": 1484789187.535, "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "2.4.0 for Java" }, }, "annotations": { "customer_category" : 124, "zip_code" : 98101, "country" : "United States", "internal" : false }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } }

键必须为字母数字才能用于筛选器。允许使用下划线。不允许使用其他符号和空格。

元数据

分段和子分段可包含一个 metadata 对象,此对象包含一个或多个字段,这些字段具有任何类型的值(包括对象和数组)。X-Ray 不会为元数据编制索引,并且值可以是任何大小,前提是分段文档不超出最大大小 (64 kB)。您可以查看由 BatchGetTraces API 返回的完整分段文档中的元数据。将保留以 debug 开头的字段键 (以下示例中为 AWS.) 以供 AWS 提供的开发工具包和客户端使用。

例 包含元数据的自定义子分段

{ "id": "0e58d2918e9038e8", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "## UserModel.saveUser", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, "subsegments": [ { "id": "0f910026178b71eb", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 58, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG", "resource_names": [ "scorekeep-user" ] } } ] }

AWS 资源数据

对于分段,aws 对象包含有关应用程序运行于的资源的信息。多个字段可应用于一个资源。例如,运行于 Elastic Beanstalk 上的多容器 Docker 环境中的应用程序包含有关 Amazon EC2 实例、该实例上运行的 Amazon ECS 容器和 Elastic Beanstalk 环境本身的信息。

aws (分段)

所有字段都是可选字段。

  • account_id – 如果您的应用程序将分段发送到其他 AWS 账户,则记录运行应用程序的账户的 ID。

  • ecs – 有关 Amazon ECS 容器的信息。

    • container – 运行应用程序的容器的容器 ID。

  • ec2 – 有关 EC2 实例的信息。

    • instance_id – EC2 实例的实例 ID。

    • availability_zone – 实例在其中运行的可用区。

    例 带插件的 AWS 数据块

    "aws": { "elastic_beanstalk": { "version_label": "app-5a56-170119_190650-stage-170119_190650", "deployment_id": 32, "environment_name": "scorekeep" }, "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-075ad396f12bc325a" }, "xray": { "sdk": "2.4.0 for Java" } }
  • elastic_beanstalk – 有关 Elastic Beanstalk 环境的信息。您可以在最新 Elastic Beanstalk 平台上名为 /var/elasticbeanstalk/xray/environment.conf 的文件中找到该信息。

    • environment_name – 环境的名称。

    • version_label – 当前部署到为请求提供服务的实例的应用程序版本的名称。

    • deployment_id数字,指示针对为请求提供服务的实例的上次成功部署的 ID。

对于子分段,记录有关应用程序访问的 AWS 服务和资源的信息。X-Ray 使用此信息来创建表示服务地图中的下游服务的推断分段。

aws (子分段)

所有字段都是可选字段。

  • operation – 针对 AWS 服务或资源调用的 API 操作的名称。

  • account_id – 如果应用程序访问其他账户中的资源,或将分段发送到其他账户,则记录拥有应用程序访问的 AWS 资源的账户的 ID。

  • region – 如果资源所在的区域不同于应用程序所在的区域,则记录前者。例如:us-west-2

  • request_id – 请求的唯一标识符。

  • queue_url – 对于 Amazon SQS 队列上的操作,为队列的 URL。

  • table_name – 对于 DynamoDB 表上的操作,为表的名称。

例 用于保存项目的 DynamoDB 调用的子分段

{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } }

错误和异常

出错时,您可以记录有关该错误及其生成的异常的详细信息。当应用程序将错误返回给用户时,在分段中记录错误;当下游调用返回错误时,在子分段中记录错误。

错误类型

将以下一个或多个字段设置为 true 可指示已发生错误。如果出现复合错误,则多个类型适用。例如,来自下游调用的 429 Too Many Requests 错误可能会导致应用程序返回 500 Internal Server Error,在此情况下,所有三种类型将适用。

  • error布尔值,指示出现客户端错误(响应状态代码为 4XX 客户端错误)。

  • throttle布尔值,指示请求已受限(响应状态代码为 429 请求过多)。

  • fault布尔值,指示出现服务器错误(响应状态代码为 5XX 服务器错误)。

通过在分段或子分段中包含 cause 对象来指示错误原因。

cause

原因可以是 16 个字符的异常 ID 或带以下字段的对象:

  • working_directory – 发生异常时的工作目录的完整路径。

  • paths – 发生异常时所使用的库或模块的路径的数组

  • exceptionsexception 对象的数组

包含有关一个或多个 exception 对象中的错误的详细信息。

exception

所有字段均可选,但 id 除外。

  • id – 异常的 64 位标识符,在同一个跟踪中的分段之间唯一,使用 16 位十六进制数

  • message – 异常消息。

  • type – 异常类型。

  • remote布尔值,指示由下游服务返回的错误导致的异常。

  • truncated整数,指示从 stack 中忽略的堆栈帧数。

  • skipped整数,指示在此异常与其子异常(此异常导致的异常)之间跳过的异常数。

  • cause – 此异常的父级(导致此异常的异常)的异常 ID。

  • stackstackFrame 对象的数组

如果可用,则记录有关 stackFrame 对象中的调用堆栈的信息。

stackFrame

所有字段都是可选字段。

  • path – 文件的相对路径。

  • line – 文件中的行。

  • label – 函数或方法名称。

SQL 查询

您可以为应用程序向 SQL 数据库发出的查询创建子分段。

sql

所有字段都是可选字段。

  • connection_string – 对于 SQL Server 连接或不使用 URL 连接字符串的其他数据库连接,记录连接字符串(不包括密码)。

  • url – 对于使用 URL 连接字符串的数据库连接,记录 URL(不包括密码)。

  • sanitized_query – 数据库查询,其任何用户提供的值已删除或由占位符替换。

  • database_type – 数据库引擎的名称。

  • database_version – 数据库引擎的版本号。

  • driver_version – 应用程序使用的数据库引擎驱动程序的名称和版本号。

  • user – 数据库用户名。

  • preparation – 如果查询使用了 PreparedCall,则为 call;如果查询使用了 PreparedStatement,则为 statement

例 具有 SQL 查询的子分段

{ "id": "3fd8634e78ca9560", "start_time": 1484872218.696, "end_time": 1484872218.697, "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com", "namespace": "remote", "sql" : { "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb", "preparation": "statement", "database_type": "PostgreSQL", "database_version": "9.5.4", "driver_version": "PostgreSQL 9.4.1211.jre7", "user" : "dbuser", "sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;" } }