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

# Amazon API Gateway 主动追踪支持 Amazon X-Ray
API Gateway

当用户请求通过 Amazon API Gateway API 传输到底层服务时，您可以使用 X-Ray 对用户请求进行跟踪和分析。API Gateway 支持对所有 API Gateway 端点类型进行 X-Ray 跟踪：区域、边缘优化和私有。您可以在提供 X-Ray 的所有Amazon Web Services 区域中将 X-Ray 与 Amazon API Gateway 结合使用。有关更多信息，请参阅《API Gateway 开发人员指南》中的[使用 Amazon X-Ray 跟踪 API Gateway API 执行情况](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-xray.html)。

**注意**  
X-Ray 仅支持通过 API Gateway 跟踪 REST API。

Amazon API Gateway 为 Amazon X-Ray 提供[主动追踪](xray-services.md)支持。在 API 阶段启用活动跟踪以对传入请求进行采样，并将跟踪发送到 X-Ray。

**如何在 API 阶段启用活动跟踪**

1. 打开 API Gateway 控制台，网址为：[https://console.aws.amazon.com/apigateway/](https://console.amazonaws.cn/apigateway/)。

1. 选择一个 API。

1. 选择一个阶段。

1. 在**日志/跟踪**选项卡上，选择**启用 X-Ray 跟踪**，然后选择**保存更改**。

1. 在左侧导航面板中，选择**资源**。

1. 如需重新部署具有新设置的 API，请选择**操作**下拉列表，然后选择**部署 API**。

API Gateway 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。您可以创建仅适用于 API 的规则，或者仅适用于包含特定标头的请求的规则。API Gateway 在分段的属性中记录标头，以及有关阶段和请求的详细信息。有关更多信息，请参阅 [配置采样规则](xray-console-sampling.md)。

**注意**  
在使用 API Gateway [HTTP 集成](https://docs.amazonaws.cn/apigateway/latest/developerguide/setup-http-integrations.html)跟踪 REST API 时，每个分段的服务名称都设置为从 API Gateway 指向 HTTP 集成端点的请求 URL 路径，结果是每个唯一的 URL 路径在 X-Ray 跟踪地图上都会显示一个服务节点。大量 URL 路径可能会导致跟踪地图超过 10,000 节点的上限，从而出现错误。  
如需最大限度减少 API Gateway 创建的服务节点数量，请考虑在 URL 查询字符串或通过 POST 的请求正文里传递参数。这两种方法都能确保参数不是 URL 路径的一部分，这可能会减少不同的 URL 路径和服务节点。

对于所有传入请求，API Gateway 将[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)添加到还没有跟踪标头的传入 HTTP 请求。

```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
```

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

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

  例如，2016 年 12 月 1 日上午 10:00（太平洋标准时间）的纪元时间为 `1480615200` 秒，或者是十六进制数字 `58406520`。
+ 跟踪的 96 位全局唯一标识符，使用 **24 个十六进制数字**。

如果禁用了活动跟踪，只要请求来自采样的请求并已开始跟踪，则该阶段仍会记录分段。例如，已检测的 Web 应用程序可通过 HTTP 客户端调用 API Gateway API。当您使用 X-Ray SDK 检测 HTTP 客户端时，将向包含采样决策的传出请求添加跟踪标头。API Gateway 读取跟踪标头并为采样请求创建分段。

如果您使用 API Gateway [为 API 生成 Java SDK，](https://docs.amazonaws.cn/apigateway/latest/developerguide/how-to-generate-sdk.html)则可以通过向客户端生成器添加一个请求处理程序来检测 SDK 客户端，这与您手动检测 Amazon SDK 客户端的方式相同。有关说明，请参阅[使用适用于 Java 的 X-Ray SD Amazon K 追踪 SDK 调用](xray-sdk-java-awssdkclients.md)：