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

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

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

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

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

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

示例应用程序

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

开始使用

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

配置

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 
}

配置规范

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

日志记录配置

可以按照与 Java 版 X-Ray 开发工具包相同的方式配置 X-Ray 代理的日志级别。请参阅 日志记录，详细了解如何使用适用于 Java 的 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.11.0</version> 
  </dependency> 
  </dependencies>

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

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

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

故障排除

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

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

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

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

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

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

您在应用程序日志中是否看到多条错误消息，其内容类似于“禁止 Amazon X-Ray 上下文缺失异常”？

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

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

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

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

您是否制定采样规则？

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