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

# 正在将跟踪数据发送到 Amazon X-Ray
发送数据

您可以分段文档的形式将跟踪数据发送到 X-Ray。分段文档是 JSON 格式的字符串，其中包含有关您的应用程序在请求服务中所做工作的信息。您的应用程序可以将它自身所做工作的数据记录在分段中，将使用下游服务和资源的工作的数据记录在子分段中。

分段记录有关您的应用程序所做工作的信息。区段至少记录在一项任务上花费的时间、一个名称和两个 IDs。当请求在多个服务之间传输时，跟踪 ID 可对请求进行追踪。分段 ID 跟踪单个服务为请求所做的工作。

**Example 最小完成分段**  

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

当收到请求时，您可以发送正在运行的分段作为占位符，直到该请求完成。

**Example 正在进行分段**  

```
{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  “in_progress”: true
}
```

您可以使用 [`PutTraceSegments`](#xray-api-segments) 或[通过 X-Ray 进程守护程序](#xray-api-daemon)直接将分段发送给 X-Ray。

大多数应用程序使用 Amazon SDK 调用其他服务或访问资源。在*子分段*中记录有关下游调用的信息。X-Ray 使用子分段来确定未发送分段的下游服务，并在服务图上为其创建条目。

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

**Example 子分段**  
子分段具有 `type` 的 `subsegment` 以及标识父分段的 `parent_id`。  

```
{
  "name" : "www2.example.com",
  "id" : "70de5b6f19ff9a0c",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  “end_time” : 1.478293361449E9,
  “type” : “subsegment”,
  “parent_id” : “70de5b6f19ff9a0b”
}
```

有关可包含在分段和子分段中的字段和值的更多信息，请参阅[Amazon X-Ray 分段文档](xray-api-segmentdocuments.md)。

**Topics**
+ [

## 正在生成跟踪 IDs
](#xray-api-traceids)
+ [

## 使用 PutTraceSegments
](#xray-api-segments)
+ [

## 将分段文档发送到 X-Ray 进程守护程序
](#xray-api-daemon)

## 正在生成跟踪 IDs


要将数据发送到 X-Ray，必须为每个请求生成一个唯一的跟踪 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 现在支持使用创建的跟踪 IDs OpenTelemetry 以及任何其他符合 [W3C 跟踪上下文](https://www.w3.org/TR/trace-context/)规范的框架。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID `4efaaf4d1e8720b39541901950019ee5` 在发送到 X-Ray 时，应与 `1-4efaaf4d-1e8720b39541901950019ee5` 的格式相同。X-Ray 跟踪 IDs 包括以 Unix 纪元时间为单位的原始请求时间戳，但是当以 IDs X-Ray 格式发送 W3C 跟踪时，这不是必需的。

您可以编写脚本来生成 X-Ray 跟踪 IDs 以供测试。以下是两个示例。

**Python**

```
import time
import os
import binascii

START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```

**Bash**

```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```

有关创建跟踪 IDs 并将区段发送到 X-Ray 守护程序的脚本，请参阅 Scorekeeep 示例应用程序。
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash - [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)

## 使用 PutTraceSegments


您可以使用 [https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html](https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html) API 上传分段文档。该 API 只有一个参数 `TraceSegmentDocuments`，该参数采用 JSON 分段文档列表。

通过 AWS CLI，使用 `aws xray put-trace-segments` 命令将分段文档直接发送给 X-Ray。

```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
    "UnprocessedTraceSegments": []
}
```

**注意**  
Windows 命令处理器和 Windows PowerShell 对 JSON 字符串中的引号和转义有不同的要求。有关详细信息，请参阅 [ 用户指南中的](https://docs.amazonaws.cn/cli/latest/userguide/cli-using-param.html#quoting-strings)为字符串加引号 Amazon CLI 。

输出列出任何处理失败的分段。例如，如果跟踪 ID 中的日期是很久以前，您会看到一个如下所示的错误。

```
{
    "UnprocessedTraceSegments": [
        {
            "ErrorCode": "InvalidTraceId",
            "Message": "Invalid segment. ErrorCode: InvalidTraceId",
            "Id": "6226467e3f845502"
        }
    ]
}
```

您可以同时传递多个分段文档，中间用空格分隔。

```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```

## 将分段文档发送到 X-Ray 进程守护程序


您可以不将分段文档发送到 X-Ray，而是将分段和子分段发送到 X-Ray 进程守护程序，进程守护程序将缓存它们，然后分批上传到 X-Ray API。X-Ray SDK 将分段文档发送到进程守护程序以避免直接调用 Amazon 。

**注意**  
请参阅 [在本地运行 X-Ray 进程守护程序](xray-daemon-local.md) 获得有关运行进程守护程序的说明。

通过 UDP 端口 2000 发送 JSON 格式分段，在前面加上进程守护程序标头 `{"format": "json", "version": 1}\n`

```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```

在 Linux 上，您可以从 Bash 终端将分段文档发送给进程守护程序。将标头和分段文档保存到一个文本文件中，然后使用 `/dev/udp` 以管道形式传送到 `cat`。

```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```

**Example segment.txt**  

```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```

检查[进程守护程序日志](xray-daemon.md#xray-daemon-logging)，验证它是否已将分段发送到 X-Ray。

```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```