本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon X-Ray 分段文档
分段文档

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

**分段文档**将有关分段的信息传递给 X-Ray。分段文档最多可为 64KB，并且包含一个带子分段的完整分段、指示请求正在进行中的分段部分或一个单独发送的子分段。您可以使用 [https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html](https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html) API 将分段文档直接发送到 X-Ray。

X-Ray 将编译和处理分段文档以生成可查询的**跟踪摘要**和**完整跟踪**，您可以分别使用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) 和 [https://docs.amazonaws.cn/xray/latest/api/API_BatchGetTraces.html](https://docs.amazonaws.cn/xray/latest/api/API_BatchGetTraces.html) API 访问二者。除了您发送到 X-Ray 的分段和子分段之外，服务还使用子分段中的信息生成**推断分段**并将其添加到完整跟踪。推断分段表示跟踪地图中的下游服务和资源。

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

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

在使用 X-Ray SDK 检测应用程序时，此 SDK 将为您生成分段文档。此 SDK 通过本地 UDP 端口将分段文档传输到 [X-Ray 进程守护程序](xray-daemon.md)，而不是直接将分段文档发送到 X-Ray。有关更多信息，请参阅 [将分段文档发送到 X-Ray 进程守护程序](xray-api-sendingdata.md#xray-api-daemon)。

**Topics**
+ [

## 分段字段
](#api-segmentdocuments-fields)
+ [

## 子分段
](#api-segmentdocuments-subsegments)
+ [

## HTTP 请求数据
](#api-segmentdocuments-http)
+ [

## 注释
](#api-segmentdocuments-annotations)
+ [

## 元数据
](#api-segmentdocuments-metadata)
+ [

## Amazon 资源数据
](#api-segmentdocuments-aws)
+ [

## 错误和异常
](#api-segmentdocuments-errors)
+ [

## SQL 查询
](#api-segmentdocuments-sql)

## 分段字段


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

**Example 最小完成分段**  

```
{
  "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` - 连接源自单个客户端请求的所有分段和子分段的唯一标识符。

**X-Ray 跟踪 ID 格式**

  X-Ray `trace_id` 由以连字符分隔的三组数字组成。例如 `1-58406520-a006649127e371903a2de979`。这包括：
  + 版本号，即 `1`。
  + 原始请求的时间，采用 Unix 纪元时间，为 **8 个十六进制数字**。

    例如，2016 年 12 月 1 日上午 10:00（太平洋标准时间）的纪元时间为 `1480615200` 秒，或者是十六进制数字 `58406520`。
  + 跟踪的 96 位全局唯一标识符，使用 **24 个十六进制数字**。
**注意**  
X-Ray 现在支持通过 OpenTelemetry 和任何其他符合 [W3C 跟踪上下文规范](https://www.w3.org/TR/trace-context/)的框架创建的跟踪 ID。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID `4efaaf4d1e8720b39541901950019ee5` 在发送到 X-Ray 时，应与 `1-4efaaf4d-1e8720b39541901950019ee5` 的格式相同。虽然 X-Ray 跟踪 ID 包含以 Unix 纪元时间为单位的原始请求时间戳，但在以 X-Ray 格式发送 W3C 跟踪 ID 时，这不是必需的。
**跟踪 ID 安全性**  
跟踪 ID 显示在[响应标头](xray-concepts.md#xray-concepts-tracingheader)中。使用安全的随机算法生成跟踪 ID，确保攻击者无法计算未来的跟踪 ID 并使用这些 ID 向您的应用程序发送请求。
+ `start_time` - 表示分段的创建时间的**数字**，采用浮点秒数的纪元时间。例如，`1480615200.010` 或 `1.480615200010E9`。使用所需数量的小数位。建议使用微秒解析（如果可用）。
+ `end_time` - 表示分段的关闭时间的**数字**。例如，`1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` - ** **布尔值`true`，设置为 ，而不是指定 `end_time` 以记录分段已经启动但未完成。在您的应用程序接收到需要长时间提供服务的请求时发送进行中的分段，用于跟踪请求接收。发送了响应之后，发送完成分段以覆盖进行中分段。仅为每个请求发送一个完整分段，以及一个或零个进行中分段。

**服务名称**  
分段的 `name` 应该与生成该分段的服务的域名或逻辑名称相匹配。但是，并未强制执行此规则。任何拥有 [https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html](https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html) 权限的应用程序均可发送任何名称的分段。

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

**可选分段字段**
+ `service` - 一个包含应用程序的相关信息的对象。
  + `version` - 一个标识为请求提供服务的应用程序版本的字符串。
+ `user` - 一个标识发送请求的用户的字符串。
+ `origin` - 运行您的应用程序的 Amazon 资源类型。

**支持的值**
  + `AWS::EC2::Instance` - 一个 Amazon EC2 实例。
  + `AWS::ECS::Container` — 一个 Amazon ECS 容器。
  + `AWS::ElasticBeanstalk::Environment` - 一个 Elastic Beanstalk 环境。

  如果您的应用程序适用多个值，请使用最具体的值。例如，一个多容器 Docker Elastic Beanstalk 环境在一个 Amazon ECS 容器上运行您的应用程序，该容器反过来又在 Amazon ECS 实例上运行。在这种情况下，您应将源设为 `AWS::ElasticBeanstalk::Environment`，因为环境是另外两种资源的父级。
+ `parent_id` - 您在请求源自检测过的应用程序时指定的子分段 ID。X-Ray SDK 将父级子分段 ID 添加到下游 HTTP 调用的[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
+ `http` - [`http`](#api-segmentdocuments-http) 对象，包含原始 HTTP 请求的相关信息。
+ `aws` - [`aws`](#api-segmentdocuments-aws) 对象包含有关应用程序为请求提供服务的 Amazon 资源的信息。
+ `error`、`throttle`、`fault` 和 `cause` - [错误](#api-segmentdocuments-errors)字段，指示出现错误并且包含有关导致错误的异常的信息。
+ `annotations`：[`annotations`](#api-segmentdocuments-annotations) 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
+ `metadata`：[`metadata`](#api-segmentdocuments-metadata) 对象，包含要存储在分段中的任何附加数据。
+ `subsegments` - [`subsegment`](#api-segmentdocuments-subsegments) 对象**数组**。

## 子分段


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

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

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

**Example 带有嵌入式子分段的分段**  
独立子分段具有 `type` 的 `subsegment` 以及标识父分段的 `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 已收到请求，然后在完成原始请求之前单独发送子分段来跟踪这些请求。

**Example 正在进行分段**  

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

**Example 独立子分段**  
独立子分段具有 `type` 的 `subsegment`，一个 `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.010` 或 `1.480615200010E9`。
+ `end_time` - 表示子分段的关闭时间的**数字**。例如，`1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` - 设置为 `true` 的**布尔值**，而不是指定 `end_time` 以记录子分段已经启动但未完成。仅为每个下游请求发送一个完整子分段，以及一个或零个进行中子分段。
+ `trace_id` - 子分段的父分段的跟踪 ID。仅在单独发送子分段时是必需的。

**X-Ray 跟踪 ID 格式**

  X-Ray `trace_id` 由以连字符分隔的三组数字组成。例如 `1-58406520-a006649127e371903a2de979`。这包括：
  + 版本号，即 `1`。
  + 原始请求的时间，采用 Unix 纪元时间，为 **8 个十六进制数字**。

    例如，2016 年 12 月 1 日上午 10:00（太平洋标准时间）的纪元时间为 `1480615200` 秒，或者是十六进制数字 `58406520`。
  + 跟踪的 96 位全局唯一标识符，使用 **24 个十六进制数字**。
**注意**  
X-Ray 现在支持通过 OpenTelemetry 和任何其他符合 [W3C 跟踪上下文规范](https://www.w3.org/TR/trace-context/)的框架创建的跟踪 ID。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID `4efaaf4d1e8720b39541901950019ee5` 在发送到 X-Ray 时，应与 `1-4efaaf4d-1e8720b39541901950019ee5` 的格式相同。虽然 X-Ray 跟踪 ID 包含以 Unix 纪元时间为单位的原始请求时间戳，但在以 X-Ray 格式发送 W3C 跟踪 ID 时，这不是必需的。
+ `parent_id` - 子分段的父分段的分段 ID。仅在单独发送子分段时是必需的。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
+ `type` - `subsegment`。仅在单独发送子分段时是必需的。

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

**可选子分段字段**
+ `namespace` - 对于 AWS SDK 调用，为 `aws`；对于其他下游调用，为 `remote`。
+ `http` - [`http`](#api-segmentdocuments-http) 对象，包含有关传出 HTTP 调用的信息。
+ `aws` - [`aws`](#api-segmentdocuments-aws) 对象，包含有关应用程序调用的下游 Amazon 资源的信息。
+ `error`、`throttle`、`fault` 和 `cause` - [错误](#api-segmentdocuments-errors)字段，指示出现错误并且包含有关导致错误的异常的信息。
+ `annotations` - [`annotations`](#api-segmentdocuments-annotations) 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
+ `metadata` - [`metadata`](#api-segmentdocuments-metadata) 对象，包含要存储在分段中的任何附加数据。
+ `subsegments` - [`subsegment`](#api-segmentdocuments-subsegments) 对象**数组**。
+ `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 会将跟踪视为已中断，直至下游服务上传一个分段，此分段的 `parent_id` 与包含此数据块的子分段的 `id` 匹配。
+ `response` - 有关响应的信息。
  + `status` - 指示响应的 HTTP 状态的**整数**。
  + `content_length` - 指示响应正文长度（以字节为单位）的**整数**。

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

**Example 由 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.11.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
    }
  }
```

**Example 下游 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
    }
  }
}
```

**Example 下游 HTTP 调用的推断分段**  

```
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "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 条注释编制索引。

**Example 包含注释的 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.11.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 不会为元数据编制索引，并且值可以是任何大小，前提是分段文档不会超出最大大小 (64KB)。您可以查看由 [https://docs.amazonaws.cn/xray/latest/api/API_BatchGetTraces.html](https://docs.amazonaws.cn/xray/latest/api/API_BatchGetTraces.html) API 返回的完整分段文档中的元数据。将保留以 `debug` 开头的字段键（以下示例中为 `AWS.`）以供 Amazon 提供的 SDK 和客户端使用。

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

```
{
  "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"
        ]
      }
    }
  ]
}
```

## Amazon 资源数据


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

**`aws` (分段)**

所有字段都是可选字段。
+ `account_id` - 如果您的应用程序将分段发送到其他 Amazon Web Services 账户，则记录运行应用程序的账户的 ID。
+ `cloudwatch_logs`— 描述单个 CloudWatch 日志组的对象数组。
  + `log_group` - CloudWatch 日志组名称。
  + `arn` - CloudWatch 日志组 ARN。
+ `ec2` - 有关 Amazon EC2 实例的信息。
  + `instance_id` - EC2 实例的实例 ID。
  + `instance_size` - EC2 实例的类型。
  + `ami_id`— Amazon 系统映像 ID。
  + `availability_zone` - 实例在其中运行的可用区。
+ `ecs` - 有关 Amazon ECS 实例的信息。
  + `container`— 您的容器的主机名。
  + `container_id`— 您的容器的完整容器 ID。
  + `container_arn` - 容器实例的 ARN。
+ `eks` - 有关 Amazon EKS 集群的信息。
  + `pod`— EKS 容器组的主机名。
  + `cluster_name` - EKS 集群名称。
  + `container_id`— 您的容器的完整容器 ID。
+ `elastic_beanstalk`— 有关 Elastic Beanstalk 环境的信息。您可以在最新 Elastic Beanstalk 平台上名为 `/var/elasticbeanstalk/xray/environment.conf` 的文件中找到该信息。
  + `environment_name` – 环境名称。
  + `version_label` - 当前部署到为请求提供服务的实例的应用程序版本的名称。
  + `deployment_id` - **数字**，指示针对为请求提供服务的实例的上次成功部署的 ID。
+ `xray` – 有关所使用检测的类型和版本的元数据。
  + `auto_instrumentation` – 布尔值，指示是否使用了自动检测（例如，Java 代理）。
  + `sdk_version` - 正在使用的 SDK 或代理的版本。
  + `sdk` - SDK 类型。

**Example 带有插件的 Amazon 块**  

```
"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",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}
```

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

**`aws` (子分段)**

所有字段都是可选字段。
+ `operation` - 针对 Amazon Web Services 服务或资源调用的 API 操作的名称。
+ `account_id` - 如果应用程序访问其他账户中的资源，或将分段发送到其他账户，则记录拥有应用程序访问的 Amazon 资源的账户的 ID。
+ `region` - 如果资源所在的区域不同于应用程序所在的区域，则记录前者。例如 `us-west-2`。
+ `request_id` - 请求的唯一标识符。
+ `queue_url` - 对于 Amazon SQS 队列上的操作，为队列的 URL。
+ `table_name` - 对于 DynamoDB 表上的操作，为表的名称。

**Example 对 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` - 发生异常时所使用的库或模块的路径的**数组**。
+ `exceptions` - **异常**对象的**数组**。

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

**`exception`**

所有字段都是可选字段。
+ `id` - 异常的 64 位标识符，在同一个跟踪中的分段之间唯一，使用 **16 位十六进制数**。
+ `message` - 异常消息。
+ `type` - 异常类型。
+ `remote` - **布尔值**，指示由下游服务返回的错误导致的异常。
+ `truncated` - **整数**，指示从 `stack` 中忽略的堆栈帧数。
+ `skipped` - **整数**，指示在此异常与其子异常（此异常导致的异常）之间跳过的异常数。
+ `cause` - 此异常的父级（导致此异常的异常）的异常 ID。
+ `stack` - **stackFrame** 对象的**数组**。

如果可用，则记录有关 **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`。

**Example 具有 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=?;"
  }
}
```