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

# Amazon X-Ray 适用于 Java 的自动检测代理
自动检测代理

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

适用于 Java 的 Amazon X-Ray 自动检测代理是一种跟踪解决方案，只需最少的开发工作即可对 Java Web 应用程序进行检测。该代理能够跟踪基于 Servlet 的应用程序，以及使用支持的框架和库发出的该代理所有的下游请求。其中包括下游 Apache HTTP 请求、 Amazon SDK 请求以及使用 JDBC 驱动程序进行的 SQL 查询。该代理跨线程传播 X-Ray 上下文，包括所有活动分段和子分段。Java 代理仍然可以使用 X-Ray SDK 的所有配置和多功能性。选择的都是合适的默认值以确保轻松就可以使用该代理。

X-Ray 代理解决方案最适合基于 Servlet、请求响应 Java Web 应用程序服务器。如果您的应用程序使用异步框架或者不能很好地建模为请求-响应服务，则可能需要考虑改用 SDK 进行手动检测。 

X-Ray 代理是使用分布式系统理解工具包（简称 DiSCo）构建的。Di SCo 是一个开源框架，用于构建可在分布式系统中使用的 Java 代理。虽然使用 X-Ray 代理不需要了解 DiSCo ，但您可以通过访问其[主页](https://github.com/awslabs/disco)来了解有关该项目的更多信息 GitHub。X-Ray 代理也是完全开源的。要查看源代码、做出贡献或提出有关代理的问题，请访问代理[的存储库 GitHub](https://github.com/aws/aws-xray-java-agent)。

## 示例应用程序


该[eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)示例应用程序适用于使用 X-Ray 代理进行检测。此分支不包含 Servlet 筛选器或记录器配置，因为这些功能由代理完成。若要在本地运行该应用程序或使用 Amazon 资源，请按照示例应用程序的自述文件中列出的步骤操作。关于如何使用示例应用程序生成 X-Ray 跟踪的说明位于[示例应用程序的教程](xray-scorekeep.md)中。

## 开始使用


请按照以下步骤操作，开始在您自己的应用程序中使用 X-Ray 自动检测 Java 代理。

1. 在环境中运行 X-Ray 进程守护程序。有关更多信息，请参阅 [Amazon X-Ray 守护程序](xray-daemon.md)。

1. 下载[代理的最新发行版](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip)。解压缩存档并记下其在文件系统中的位置。其内容应与以下内容类似。

   ```
   disco 
   ├── disco-java-agent.jar 
   └── disco-plugins 
       ├── aws-xray-agent-plugin.jar 
       ├── disco-java-agent-aws-plugin.jar 
       ├── disco-java-agent-sql-plugin.jar 
       └── disco-java-agent-web-plugin.jar
   ```

1. 修改应用程序的 JVM 参数使其包含以下内容，以启用代理。如适用，请确保将 `-javaagent` 参数放在 `-jar` 参数*之前*。修改 JVM 参数的过程因启动 Java 服务器所使用的工具和框架而异。请参阅服务器框架的文档了解详细指南。

   ```
   -javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
   ```

1. 设置 `AWS_XRAY_TRACING_NAME` 环境变量或 `com.amazonaws.xray.strategy.tracingName` 系统属性以指定您的应用程序在 X-Ray 控制台上的显示方式。如果未提供名称，则使用默认名称。

1. 重启服务器或容器。现在，会跟踪传入的请求及其下游调用。如果没有看到预期结果，请参阅[问题排查](#XRayAutoInstrumentationAgent-Troubleshooting)。

## 配置


X-Ray 代理由用户提供的外部 JSON 文件进行配置。默认情况下，此文件位于名为“`xray-agent.json`”的用户的类路径的根目录中（例如，在其 `resources` 目录中）。可以将 `com.amazonaws.xray.configFile` 系统属性设置为配置文件的绝对系统文件路径，为配置文件配置自定义位置。

示例配置文件如下所示。

```
{     
    "serviceName": "XRayInstrumentedService", 
    "contextMissingStrategy": "LOG_ERROR", 
    "daemonAddress": "127.0.0.1:2000", 
    "tracingEnabled": true, 
    "samplingStrategy": "CENTRAL",     
    "traceIdInjectionPrefix": "prefix",     
    "samplingRulesManifest": "/path/to/manifest",     
    "awsServiceHandlerManifest": "/path/to/manifest",     
    "awsSdkVersion": 2,     
    "maxStackTraceLength": 50,     
    "streamingThreshold": 100,     
    "traceIdInjection": true,     
    "pluginsEnabled": true,     
    "collectSqlQueries": false 
}
```

### 配置规范


下表介绍了每个属性的有效值。属性名称区分大小写，但它们的键不区分大小写。可以被环境变量和系统属性覆盖的属性，其优先级顺序始终先是环境变量、系统属性，然后再是配置文件。有关您可以覆盖的属性的相关信息，请参阅[环境变量](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)。所有字段都是可选字段。


|  属性名称  |  Type  |  有效值  |  说明  |  环境变量  |  系统属性  |  默认  | 
| --- | --- | --- | --- | --- | --- | --- | 
|  serviceName  |  字符串  |  任何字符串  |  将在 X-Ray 控制台中显示的已检测服务的名称。  |  AWS\$1XRAY\$1TRACING\$1NAME  |  com.amazonaws.xray.strategy.tracingNam  |  XRayInstrumentedService  | 
|  contextMissingStrategy  |  字符串  |  LOG\$1ERROR、IGNORE\$1ERROR  |  代理尝试使用 X-Ray 分段上下文但不存在时所采取的操作。  |  AWS\$1XRAY\$1上下文\$1缺失  |  com.amazonaws.xray.strategy contextMissingStrategy  |  LOG\$1ERROR  | 
|  daemonAddress  |  字符串  |  格式化的 IP 地址和端口，或者 TCP 和 UDP 地址列表  |  代理用于与 X-Ray 进程守护程序通信的地址。  |  AWS\$1XRAY\$1守护进程\$1地址  |  com.amazonaws.xray.emitter.daemonAddress  |  127.0.0.1:2000  | 
|  tracingEnabled  |  布尔值  |  True, False  |  启用 X-Ray 代理进行检测。  |  AWS\$1XRAY\$1追踪\$1已启用  |  com.amazonaws.xray.tracingEnabled  |  TRUE  | 
|  samplingStrategy  |  字符串  |  CENTRAL、LOCAL、NONE、ALL  |  代理使用的采样策略。ALL 捕获所有请求，NONE 不捕获任何请求。请参阅[采样规则](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling)。  |  不适用  |  不适用  |  CENTRAL  | 
|  traceIdInjection前缀  |  字符串  |  任何字符串  |  在日志中注入跟踪 IDs 之前包含提供的前缀。  |  不适用  |  不适用  |  无（空字符串）  | 
|  samplingRulesManifest  |  字符串  |  绝对文件路径  |  自定义采样规则文件的路径，该文件用作本地采样策略的采样规则或中心策略的后备规则的来源。  |  不适用  |  不适用  |   [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json)   | 
|   awsServiceHandler清单   |  字符串  |  绝对文件路径  |  自定义参数允许列表的路径，可从 Amazon SDK 客户端捕获其他信息。  |  不适用  |  不适用  |   [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json)   | 
|  awsSdkVersion  |  整数  |  1、2  |  您正在使用的 [Amazon SDK for Java](https://docs.amazonaws.cn/sdk-for-java/index.html) 的版本。如果 `awsServiceHandlerManifest` 也没有设置，请会被忽略。  |  不适用  |  不适用  |  2  | 
|  maxStackTrace长度  |  整数  |  非负整数  |  一个跟踪中记录的堆栈跟踪的最大行数。  |  不适用  |  不适用  |  50  | 
|  streamingThreshold  |  整数  |  非负整数  |  至少在关闭这么多子分段之后，它们会被流式传输到守护程序 out-of-band，以避免区块太大。  |  不适用  |  不适用  |  100  | 
|  traceIdInjection  |  布尔值  |  True, False  |  如果还添加了[日志记录配置](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)中所述的依赖项和配置，则启用 X-Ray 跟踪 ID 注入日志。否则，不执行任何操作。  |  不适用  |  不适用  |  TRUE  | 
|  pluginsEnabled  |  布尔值  |  True, False  |  启用用于记录有关您正在操作的 Amazon 环境的元数据的插件。请参阅[插件](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins)。  |  不适用  |  不适用  |  TRUE  | 
|  collectSqlQueries  |  布尔值  |  True, False  |  尽量将 SQL 查询字符串记录在 SQL 子分段中。  |  不适用  |  不适用  |  FALSE  | 
|  contextPropagation  |  布尔值  |  True, False  |  如果是 true，则在线程之间自动传播 X-Ray 上下文。否则，需要使用 Thread Local 来存储上下文，并且需要手动跨线程传播。  |  不适用  |  不适用  |  TRUE  | 

### 日志记录配置


可以按照与 X-Ray SDK for Java 相同的方式配置 X-Ray 代理的日志级别。请参阅 [日志记录](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)，详细了解如何使用 X-Ray SDK for Java 配置日志记录。

### 手动检测


如果希望在代理的自动检测之外再执行手动检测，请将 X-Ray SDK 作为依赖项添加到您的项目。请注意，[跟踪传入请求](xray-sdk-java-filters.md)中提及的 SDK 自定义 Servlet 筛选器与 X-Ray 代理不兼容。

**注意**  
您必须使用最新版本的 X-Ray SDK 来执行手动检测，同时还要使用代理。

如果您正在处理的是 Maven 项目，请将以下依赖项添加到您的 `pom.xml` 文件中。

```
<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>
```

如果您正在处理的是 Gradle 项目，请将以下依赖项添加到您的 `build.gradle` 文件中。

```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' 
```

在使用代理 IDs时，除了[注释、元数据和用户之外，](xray-sdk-java-segment.md)您还可以添加[自定义子细分](xray-sdk-java-subsegments.md)，就像使用普通 SDK 一样。代理会自动跨线程传播上下文，因此在使用多线程应用程序时，无需使用任何解决方法即可传播上下文。

## 问题排查


由于代理提供全自动检测功能，因此在遇到问题时可能很难确定问题的根本原因。如果 X-Ray 代理无法按预期运行，请查看以下问题和解决方案。X-Ray 代理和 SDK 使用 Jakarta Commons Logging（JCL）。若要查看日志记录输出，请确保将 JCL 桥接到您在类路径上的日志记录后端，如以下示例所示：`log4j-jcl` 或 `jcl-over-slf4j`。

### 问题：我的应用程序上已经启用了 Java 代理，但在 X-Ray 控制台上却什么都看不到。


 **X-Ray 进程守护程序是否在同一台计算机上运行？** 

如果不是，请参阅 [X-Ray 进程守护程序文档](https://docs.amazonaws.cn/xray/latest/devguide/xray-daemon.html)进行设置。

 **在应用程序日志中，是否看到类似于“正在初始化 X-Ray 代理记录器”这样的消息？** 

如果您已正确将代理添加到应用程序中，则在应用程序启动时，在开始接受请求之前，将在信息级别记录此消息。如果没有出现此消息，则说明您的 Java 进程未运行 Java 代理。确保您已正确执行所有设置步骤，不存在错别字。

 **在您的应用程序日志中，您是否看到几条错误消息，上面写着 “禁止 Amazon X-Ray 上下文缺失异常” 之类的内容？** 

之所以出现这些错误，是因为代理正在尝试检测下游请求，例如 Amazon SDK 请求或 SQL 查询，但代理无法自动创建区段。如果您看到其中许多错误消息，则代理可能并不是最适合您用例的工具，可能需要考虑改用 X-Ray SDK 进行手动检测。或者，可以启用 X-Ray SDK [调试日志](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)，以查看上下文缺失异常发生位置的堆栈跟踪。可以用自定义分段封装代码的这些部分，这样可以解决这些错误。请参阅[检测启动代码](scorekeep-startup.md)中的示例代码，查看使用自定义分段包装下游请求的示例。

### 问题：我预期的一些分段没有出现在 X-Ray 控制台上


 **您的应用程序是否使用多线程？**

 如果您希望创建的某些分段未出现在控制台上，则可能是应用程序中的后台线程造成的。如果您的应用程序使用 “触发和忘记” 的后台线程执行任务，例如使用软件开发工具包一次性调用 Lambda 函数，或者定期轮询某些 HTTP 端点，则在代理跨线程传播上下文时，可能会使代理感到困惑。 Amazon 若要验证您遇到的是不是这个问题，可以启用 X-Ray SDK 调试日志并查看如下所示的消息：*未发射名为 <NAME> 的分段，因为它是正在进行中的子分段的父级*。若要解决此问题，可以尝试在服务器返回前加入后端线程以确保记录下在其中完成的全部工作。或者，也可以将代理的 `contextPropagation` 配置设置为 `false`，在后台禁用上下文传播。如果这样做，则必须使用自定义分段手动检测这些线程，或忽略它们造成的上下文缺失异常。

**您是否制定采样规则？** 

 如果 X-Ray 主机上出现了看似随机或意想不到的分段，或者您期望出现在控制台上的分段没有出现，那么可能遇到了采样问题。X-Ray 代理使用 X-Ray 控制台中的规则将集中采样应用于其创建的所有分段。默认规则为每秒 1 个分段，之后再加上 5% 的分段进行采样。这意味着可能不会对使用代理快速创建的区段进行采样。要解决这个问题，应该在 X-Ray 控制台上创建自定义采样规则，对所需的分段进行适当采样。有关更多信息，请参阅[采样](xray-console-sampling.md)。