本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS X-Ray 适用于 Java 的 SDK
**注意**
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
X-Ray SDK for Java 是一组面向 Java Web 应用程序的库，可提供类和方法来生成跟踪数据并将跟踪数据发送给 X-Ray 进程守护程序。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 AWS SDK、HTTP 客户端或 SQL 数据库连接器对下游服务进行的调用的信息。您还可以手动创建分段并在注释和元数据中添加调试信息。
X-Ray SDK for Java 是一个开源项目。你可以关注该项目并在 [github 上 GitHub提交议题和拉取请求。 com/aws/aws](https://github.com/aws/aws-xray-sdk-java)-xray-sdk-java
首先通过[添加`AWSXRayServletFilter` 作为 servlet 筛选器](xray-sdk-java-filters.md)来跟踪传入请求。servlet 筛选器会创建[分段](xray-concepts.md#xray-concepts-segments)。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。
从版本 1.3 开始，您可以使用 [Spring 中的面向方面的编程 (AOP)](xray-sdk-java-aop-spring.md) 来检测应用程序。这意味着你可以在应用程序运行时对其进行检测，而无需在 AWS应用程序的运行时中添加任何代码。
接下来，使用适用于 Java 的 X-Ray SDK，在构建配置中包[含 SDK Instrumentor 子模块](#xray-sdk-java-dependencies)，对 适用于 Java 的 AWS SDK 客户进行检测。每当您使用已检测的客户端调用下游 AWS 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 AWS 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。
如果您不想检测所有下游调用 AWS 服务，则可以省略 Instrumentor 子模块，然后选择要检测的客户端。通过[向 AWS SDK 服务客户端添加`TracingHandler`](xray-sdk-java-awssdkclients.md)来检测各个客户端。
其他 X-Ray SDK for Java 子模块为对 HTTP Web APIs 和 SQL 数据库的下游调用提供了工具。您可以[使用 X-Ray SDK for Java 的 `HTTPClient` 版本和 Apache HTTP 子模块中的 `HTTPClientBuilder`](xray-sdk-java-httpclients.md) 来检测 Apache HTTP 客户端。要检测 SQL 查询，请[将 SDK 的拦截程序添加到数据源](xray-sdk-java-sqlclients.md)。
在开始使用 SDK 后，通过[配置记录器和 servlet 筛选器](xray-sdk-java-configuration.md)来自定义其行为。您可以添加插件来记录有关应用程序上运行的计算资源的数据，通过定义采样规则来自定义采样行为，设置日志级别以在应用程序日志中查看来自开发工具包的更多或更少的信息。
记录有关请求以及应用程序在[注释和元数据](xray-sdk-java-segment.md)中所做的工作的其他信息。注释是简单的键值对，已为这些键值对编制索引以用于[筛选条件表达式](xray-console-filters.md)，以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低，并且可以记录整个对象和数组 - 可序列化为 JSON 的任何项目。
**注释和元数据**
注释和元数据是您使用 X-Ray 开发工具包添加到分段的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始分段中查看。您授予 X-Ray 读取权限的任何人都可以查看这些数据。
当代码中具有大量检测的客户端时，一个请求分段可包含许多子分段，检测的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在[自定义子分段](xray-sdk-java-subsegments.md)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段，并记录子分段的元数据和注释，而不是编写父分段的所有内容。
## 子模块
您可以从 Maven 下载 X-Ray SDK for Java。X-Ray SDK for Java 按使用案例被拆分为子模块，其中的材料清单用于版本管理：
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/)（必需） - 用于创建分段和传输分段的基本功能。包括 `AWSXRayServletFilter` 用于检测传入请求。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— 通过添加跟踪 适用于 Java 的 AWS SDK 客户端作为请求处理程序，对客户端发 AWS 服务 出的调用进行监测。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— 通过添加跟踪客户端作为请求拦截器，对 AWS 服务 使用 适用于 Java 的 AWS SDK 2.2 及更高版本的客户端进行的调用进行监测。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— 使用`aws-xray-recorder-sdk-aws-sdk`，自动对所有 适用于 Java 的 AWS SDK 客户进行仪器。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— 使用`aws-xray-recorder-sdk-aws-sdk-v2`，自动检测所有 适用于 Java 的 AWS SDK 2.2 及更高版本的客户端。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/) - 检测使用 Apache HTTP 客户端进行的传出 HTTP 调用。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/) - 为 Spring AOP 框架应用程序提供拦截程序。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/) - 检测由 JDBC 对 PostgreSQL 数据库进行的传出调用。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/) - 检测由 JDBC 对 MySQL 数据库进行的传出调用。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/) - 提供材料清单，您可以用它来指定用于所有子模块的版本。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— 从您收集的 X-Ray 细分中发布未抽样的亚马逊 CloudWatch 指标。
如果您使用 Maven 或 Gradle 来构建应用程序，可[将 X-Ray SDK for Java 添加到您的构建配置中](#xray-sdk-java-dependencies)。
有关 SDK 的类和方法的参考文档，请参阅[AWS X-Ray SDK for Java API 参考](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc)。
## 要求
适用于 Java 的 X-Ray SDK 需要 Java 8 或更高版本、Servlet API 3、 AWS SDK 和 Jackson。
该 SDK 在编译和运行时依赖于以下库：
+ AWS 适用于 Java 的 SDK 版本 1.11.398 或更高版本
+ Servlet API 3.1.0
这些依赖项在 SDK 的 `pom.xml` 文件中声明，如果您使用 Maven 或 Gradle 生成则自动包括在内。
如果您使用包括在 X-Ray SDK for Java 中的库，则必须使用包括的版本。例如，如果您在运行时已经依赖于 Jackson 并在部署中为该依赖项包括了 JAR 文件，则必须删除这些 JAR 文件，因为 SDK JAR 包括其自己的 Jackson 库版本。
## 依赖关系管理
可从 Maven 获得 X-Ray SDK for Java：
+ **组** – `com.amazonaws`
+ **构件** – `aws-xray-recorder-sdk-bom`
+ **版本**：`2.11.0`
如果您使用 Maven 来生成应用程序，则在 `pom.xml` 文件中添加 SDK 作为依赖项。
**Example pom.xml - 依赖项**
```
com.amazonaws
aws-xray-recorder-sdk-bom
2.11.0
pom
import
com.amazonaws
aws-xray-recorder-sdk-core
com.amazonaws
aws-xray-recorder-sdk-apache-http
com.amazonaws
aws-xray-recorder-sdk-aws-sdk
com.amazonaws
aws-xray-recorder-sdk-aws-sdk-instrumentor
com.amazonaws
aws-xray-recorder-sdk-sql-postgres
com.amazonaws
aws-xray-recorder-sdk-sql-mysql
```
对于 Gradle，添加 SDK 作为 `build.gradle` 文件中的编译时依赖项。
**Example build.gradle - 依赖项**
```
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
compile("com.amazonaws:aws-java-sdk-dynamodb")
compile("com.amazonaws:aws-xray-recorder-sdk-core")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor")
compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
testCompile("junit:junit:4.11")
}
dependencyManagement {
imports {
mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
}
}
```
如果您使用 Elastic Beanstalk 来部署应用程序，则可以使用 Maven 或 Gradle 在每次部署时生成 on-instance，而不是生成和上传包括所有依赖项的大档案。有关使用 Gradle 的示例，请参阅[示例应用程序](xray-scorekeep.md)。
## AWS X-Ray 适用于 Java 的 X-Ray SDK 的指标
**注意**
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
本主题介绍 AWS X-Ray 命名空间、指标和维度。您可以使用适用于 Java 的 X-Ray SDK 从您收集的 X-Ray 细分中发布未采样的亚马逊 CloudWatch 指标。这些指标来自分段的开始和结束时间以及错误、故障和限制状态标志。使用这些指标可暴露子分段里的重试和依赖项问题。
CloudWatch 是一个指标存储库。指标是中的基本概念 CloudWatch ，代表一组按时间排序的数据点。您（或 AWS 服务）将指标数据点发布到其中， CloudWatch 并将有关这些数据点的统计数据作为一组有序的时间序列数据进行检索。
指标通过名称、命名空间以及一个或多个维度进行唯一定义。每个数据点都有一个时间戳和一个可选的度量单位。当请求统计数据时，返回的数据流根据命名空间、指标名称和维度加以识别。
有关的更多信息 CloudWatch，请参阅 [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/)。
### X-Ray CloudWatch 指标
`ServiceMetrics/SDK` 命名空间包括以下指标。
| 指标 | 可用统计数据 | 说明 | 单位 |
| --- | --- | --- | --- |
| `Latency` | 平均、最小、最大、计数 | 开始时间和结束时间之间的差异。平均、最小和最大都描述操作延迟。计数描述调用次数。 | 毫秒 |
| `ErrorRate` | 平均、总计 | 导致错误的失败请求率，显示 `4xx Client Error` 状态码。 | 百分比 |
| `FaultRate` | 平均、总计 | 导致故障的失败跟踪率，显示 `5xx Server Error` 状态码。 | 百分比 |
| `ThrottleRate` | 平均、总计 | 返回 `429` 状态码的受限制跟踪率。这是 `ErrorRate` 指标的子集。 | 百分比 |
| `OkRate` | 平均、总计 | 导致 `OK` 状态码的被跟踪请求率。 | 百分比 |
### X 射线 CloudWatch 尺寸
您可以用下表中的维度来优化针对经 X-Ray 检测的 Java 应用程序返回的指标。
| 维度 | 说明 |
| --- | --- |
| `ServiceType` | 服务类型，例如 `AWS::EC2::Instance` 或 `NONE`（如果为未知）。 |
| `ServiceName` | 服务的规范名称。 |
### 启用 X-Ray CloudWatch 指标
使用以下过程在已检测的 Java 应用程序中启用跟踪指标。
**配置跟踪指标**
1. 将 `aws-xray-recorder-sdk-metrics` 包添加为 Apache Maven 依赖项。有关更多信息，请参阅 [X-Ray SDK for Java Submodules](#xray-sdk-java-submodules)。
1. 启用新的 `MetricsSegmentListener()` 作为全局记录器构建的一部分。
**Example src/com/myapp/web/Startup.java**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard()
.withPlugin(new EC2Plugin())
.withPlugin(new ElasticBeanstalkPlugin())
.withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
1. 部署 CloudWatch 代理以使用亚马逊弹性计算云（亚马逊 EC2）、亚马逊弹性容器服务（亚马逊 ECS）或亚马逊 Elastic Kubernetes Service（亚马逊 EKS）收集指标：
+ 要配置 Amazon EC2，请参阅[安装 CloudWatch 代理](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html)。
+ 要配置 Amazon ECS，请参阅[使用 Container Insights 监控 Amazon ECS 容器](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html)
+ 要配置 Amazon EKS，请参阅[使用 Amazon Obs CloudWatch ervability EKS 插件安装 CloudWatch 代理](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html)。
1. 将 SDK 配置为与 CloudWatch 代理通信。默认情况下，SDK 通过地址`127.0.0.1`与 CloudWatch 代理进行通信。您可以通过将环境变量或 Java 属性设置为 `address:port` 来配置备用地址。
**Example 环境变量**
```
AWS_XRAY_METRICS_DAEMON_ADDRESS={{address:port}}
```
**Example Java 属性**
```
com.amazonaws.xray.metrics.daemonAddress={{address:port}}
```
**验证配置**
1. 登录 AWS 管理控制台 并打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。
1. 打开**指标**选项卡以观察指标的情况。
1. （可选）在 CloudWatch 控制台的**日志**选项卡上，打开`ServiceMetricsSDK`日志组。查找与主机指标相匹配的日志流，然后确认日志消息。