AWS X-Ray 分段文档

必填分段字段

• 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.010 或 1.480615200010E9。使用所需数量的小数位。建议使用微秒解析 (如果可用)。

• end_time – 表示分段的关闭时间的数字。例如，1480615200.090 或 1.480615200090E9。指定 end_time 或 in_progress。

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

可选分段字段

• 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 调用的跟踪标头。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。

• http – http 对象，包含原始 HTTP 请求的相关信息。

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

• error、throttle、fault 和 cause – error 字段，指示出现错误并且包含有关导致错误的异常的信息。

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

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

• subsegments – subsegment 对象的数组。

必填子分段字段

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

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

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

• end_time – 表示子分段的关闭时间的数字。例如，1480615200.090 或 1.480615200090E9。指定 end_time 或 in_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。仅在单独发送子分段时是必需的。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。

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

可选子分段字段

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

• http – http 对象，包含有关传出 HTTP 调用的信息。

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

• error、throttle、fault 和 cause – error 字段，指示出现错误并且包含有关导致错误的异常的信息。

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

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

• subsegments – subsegment 对象的数组。

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

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 – 指示响应正文长度（以字节为单位）的数字。

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 (子分段)

所有字段都是可选字段。

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

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

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

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

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

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

错误类型

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

• error – 布尔值，指示出现客户端错误（响应状态代码为 4XX 客户端错误）。

• throttle – 布尔值，指示请求已受限（响应状态代码为 429 请求过多）。

• fault – 布尔值，指示出现服务器错误（响应状态代码为 5XX 服务器错误）。

cause

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

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

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

• exceptions – exception 对象的数组。

exception

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

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

• message – 异常消息。

• type – 异常类型。

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

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

• skipped – 整数，指示在此异常与其子异常（此异常导致的异常）之间跳过的异常数。

• cause – 此异常的父级（导致此异常的异常）的异常 ID。

• stack – stackFrame 对象的数组。

stackFrame

所有字段都是可选字段。

• path – 文件的相对路径。

• line – 文件中的行。

• label – 函数或方法名称。

sql

所有字段都是可选字段。

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

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

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

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

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

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

• user – 数据库用户名。

• preparation – 如果查询使用了 PreparedCall，则为 call；如果查询使用了 PreparedStatement，则为 statement。