AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

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

适用于 Java 的 AWS X-Ray 自动分析代理

适用于 Java 的 AWS X-Ray 自动分析代理是一种跟踪解决方案，可分析 Java Web 应用程序，只需最少的开发工作。代理为基于 servlet 的应用程序以及使用支持的框架和库进行的所有代理下游请求启用自动 跟踪。这包括下游 Apache HTTP 请求、AWS 开发工具包请求和使用 JDBC 驱动程序进行的 SQL 查询。代理自动跨线程传播 X-Ray 上下文，包括所有活动分段和子分段。开发工具包的所有配置和多种功能仍可用于 Java 代理，并已选择合适的默认值来确保代理可以X-Ray即时工作。

代理解决方案最适合基于 servlet 的请求响应 Java Web 应用程序服务器。X-Ray如果您的应用程序使用异步框架，或建模不强于请求-响应服务，则您可能需要考虑使用开发工具包进行手动分析。 

代理是使用X-Ray分布式系统编译工具包或 构建的。DiSCo 是一个开源框架，用于构建可在分布式系统中使用的 Java 代理。DiSCo虽然了解 DiSCo 使用 X-Ray 代理不是必需的，但您可以通过访问项目在 上的GitHub主页来了解有关项目的更多信息。 代理也是完全开源的。X-Ray要查看源代码、做贡献或引发有关代理的问题，请访问其 上的存储库GitHub。

示例应用程序

eb-java-scorekeep 示例应用程序已调整为使用 代理进行检测。X-Ray此分支不包含 servlet 筛选器或记录器配置，因为这些函数是由代理完成的。要在本地或使用 AWS 资源运行应用程序，请按照示例应用程序的自述文件中的步骤操作。有关使用示例应用程序生成 X-Ray 跟踪的说明，请参阅示例应用程序的教程。

开始使用

要在您自己的应用程序中开始使用 X-Ray 自动分析 Java 代理，请执行以下步骤。

Configuration

代理由用户提供的外部 JSON 文件配置。X-Ray默认情况下，此文件位于用户的类路径（例如，在用户的resources目录xray-agent.json中）的根目录中。 您可以通过将 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 
}

配置规范

下表介绍了每个属性的有效值。属性名称区分大小写，但键不区分大小写。对于可以被环境变量和系统属性覆盖的属性，优先级的顺序始终是环境变量、系统属性，然后是配置文件。有关您可以覆盖的属性的信息，请参阅 X-Ray 文档。所有字段都是可选字段。

手动分析

如果您希望在代理的自动分析之外执行手动分析，请将 X-Ray 开发工具包作为依赖项添加到您的项目中。请注意，跟踪传入请求中提到的开发工具包的自定义 servlet 筛选器与 X-Ray 代理不兼容。

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

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

如果您在 Gradle 项目中工作，请将以下依赖项添加到您的 build.gradle 文件。

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

在使用代理时，您可以添加 自定义子分段以及注释、元数据和用户 IDs，就像使用普通开发工具包一样。代理会自动跨线程传播上下文，因此，在使用多线程应用程序时，应该无需解决方法来传播上下文。

Troubleshooting

由于代理提供了完全自动的检测，因此当您遇到问题时，可能很难确定问题的根本原因。如果 X-Ray 代理未按预期工作，请查看以下问题和解决方案。代理和开发工具包使用凸包公共日志记录 （JCL），因此，为了查看日志记录输出，您需要确保将 JCL 连接到日志记录后端的桥接位于类路径上，例如 X-Ray 或 log4j-jcl。jcl-over-slf4j

问题：我已在我的应用程序上启用 Java 代理，但在 X-Ray 控制台上看不到任何内容

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

如果没有，请参阅 X-Ray 守护程序文档进行设置。

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

如果已正确将代理添加到您的应用程序，则在应用程序启动之后，将在它开始接收请求之前以 INFO 级别记录此消息。如果该消息不存在，则表示 Java 代理未通过 Java 进程运行。确保您正确执行了所有的设置步骤，没有拼写错误。

在应用程序日志中，您是否看到一些错误消息，指出类似“Suppressing AWS X-Ray context missing exception （禁止缺少 Amazon EC2 上下文）”的内容?

发生这些错误的原因是代理尝试分析下游请求（如 AWS 开发工具包请求或 SQL 查询），但代理无法自动创建分段。如果您看到很多此类错误，代理可能不是适合您的使用案例的最佳工具，您可能需要考虑使用 X-Ray 开发工具包进行手动分析。或者，您可以启用 X-Ray 开发工具包调试日志以查看有关缺少上下文异常的出现位置的堆栈跟踪。您可以将代码的这些部分包含在自定义分段中，从而解决这些错误。有关使用自定义分段包装下游请求的示例，请参阅分析启动代码中的示例代码。

问题：控制台上不显示预计的某些分段X-Ray

您的应用程序是否使用多线程技术?

如果控制台中未显示您希望创建的某些段，可能是应用程序的背景线程造成的原因。如果您的应用程序使用后台线程“激发并忘记”执行任务，例如，使用 AWS 开发工具包对 Lambda 函数进行一次性调用，或者定期轮询一些 HTTP 终端节点，这可能会使代理在跨线程传播上下文时变得混乱。要验证是否出现了问题，请启用 X-Ray 开发工具包调试日志并检查如下消息： 不发出名为 <NAME > 的分段，因为它为进行中的子分段设置父级。要解决此问题，您可以在服务器返回之前尝试加入后台线程，以确保在其中完成的所有工作都得到记录。或者，您可以将代理的 contextPropagation 配置设置为 false，以禁用后台线程中的上下文传播。如果执行此操作，您必须手动分析具有自定义分段的线程，或忽略它们产生的缺少上下文异常。

您是否设置了采样规则?

如果 X-Ray 控制台上出现看似随机或意外的分段，或者您希望位于控制台上的分段不存在，则您可能遇到了采样问题。代理使用 X-Ray 控制台中的规则，将集中采样应用于它创建的所有分段。X-Ray默认规则为每秒 1 个分段，之后为 5% 的分段采样。这意味着，可能无法对使用代理快速创建的分段进行采样。要解决此问题，您应在 X-Ray 控制台上创建自定义采样规则，以相应地对所需的分段进行采样。有关更多信息，请参阅采样。