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

适用于 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 ，但您可以通过访问其主页来了解有关该项目的更多信息 GitHub。X-Ray 代理也是完全开源的。要查看源代码、做出贡献或提出有关代理的问题，请访问代理的存储库 GitHub。

示例应用程序

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

入门

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

在环境中运行 X-Ray 进程守护程序。有关更多信息，请参阅 Amazon X-Ray 守护程序。

下载代理的最新发行版。解压缩存档并记下其在文件系统中的位置。其内容应与以下内容类似。

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

修改应用程序的 JVM 参数使其包含以下内容，以启用代理。如适用，请确保将 -javaagent 参数放在 -jar 参数之前。修改 JVM 参数的过程因启动 Java 服务器所使用的工具和框架而异。请参阅服务器框架的文档了解详细指南。
```
-javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
```
设置 AWS_XRAY_TRACING_NAME 环境变量或 com.amazonaws.xray.strategy.tracingName 系统属性以指定您的应用程序在 X-Ray 控制台上的显示方式。如果未提供名称，则使用默认名称。
重启服务器或容器。现在，会跟踪传入的请求及其下游调用。如果没有看到预期结果，请参阅故障排除。

配置

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 
}

配置规范

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

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

日志记录配置

可以按照与 X-Ray SDK for Java 相同的方式配置 X-Ray 代理的日志级别。请参阅日志记录，详细了解如何使用 X-Ray SDK for Java 配置日志记录。

手动检测

如果希望在代理的自动检测之外再执行手动检测，请将 X-Ray SDK 作为依赖项添加到您的项目。请注意，跟踪传入请求中提及的 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时，除了注释、元数据和用户之外，您还可以添加自定义子细分，就像使用普通 SDK 一样。代理会自动跨线程传播上下文，因此在使用多线程应用程序时，无需使用任何解决方法即可传播上下文。

故障排除

由于代理提供全自动检测功能，因此在遇到问题时可能很难确定问题的根本原因。如果 X-Ray 代理无法按预期运行，请查看以下问题和解决方案。X-Ray 代理和 SDK 使用 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 SDK 请求或 SQL 查询，但代理无法自动创建区段。如果您看到其中许多错误消息，则代理可能并不是最适合您用例的工具，可能需要考虑改用 X-Ray SDK 进行手动检测。或者，可以启用 X-Ray SDK 调试日志，以查看上下文缺失异常发生位置的堆栈跟踪。可以用自定义分段封装代码的这些部分，这样可以解决这些错误。请参阅检测启动代码中的示例代码，查看使用自定义分段包装下游请求的示例。

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

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

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

您是否制定采样规则？

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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

适用 Java 的 X-Ray 开发工具包

配置