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

这些区域有：Amazon X-Ray自动检测代理程序是一种跟踪解决方案，它只需最少的开发工作即可对 Java Web 应用程序进行测试。代理启用跟踪基于 Servlet 的应用程序以及使用支持的框架和库发出的代理的所有下游请求。这包括下游 Apache HTTP 请求，AmazonSDK 请求和使用 JDBC 驱动程序发出的 SQL 查询。代理跨线程传播 X-Ray 上下文（包括所有活动段和子段）。Java 代理仍然可以使用 X-Ray SDK 的所有配置和多功能性，并且选择了合适的默认值，以确保代理以最小的工作量工作。

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

X-Ray 代理是使用分布式系统理解工具包（即 Disco）构建的。Disco 是一个用于构建可用于分布式系统的 Java 代理的开源框架。虽然没有必要了解 DisCo 使用 X-Ray 剂，但您可以通过访问其GitHub 上的主页。X-Ray 剂也是完全开放源的。要查看源代码、贡献或提出有关代理的问题，请访问其GitHub 上的存储库。

示例应用程序

这些区域有：eb-java-scoreate样品应用被调整为使用 X-Ray 剂进行仪器. 此分支不包含 servlet 过滤器或记录器配置，因为这些函数是由代理完成的。若要在本地运行应用程序或使用Amazon资源，请执行示例应用程序的自述文件中的步骤。有关使用示例应用程序生成 X-Ray 迹线的说明，请参阅示例应用程序的教程。

入门

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

在环境中运行 X-Ray 守护程序。有关更多信息，请参阅。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
```
要指定应用程序在 X-Ray 控制台上显示的名称，请将AWS_XRAY_TRACING_NAME环境变量或com.amazonaws.xray.strategy.tracingName系统属性。如果未提供名称，则使用默认名称。
重新启动服务器或容器。现在跟踪传入请求及其下游呼叫。如果您没有看到预期结果，请参阅Troubleshooting。

Configuration

X-Ray 代理由用户提供的外部 JSON 文件配置。默认情况下，此文件位于用户类路径的根目录（例如，在其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 
}

配置规范

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

属性名称	类型	有效值	描述	环境变量	系统属性	默认值
serviceName	字符串	任何字符串	检测服务的名称，它将显示在 X-Ray 控制台中。	AW_XRAY_ 跟踪 _ 名称	亚马逊 .xray.策略. 追踪名称	XRA 工具服务
上下文缺失策略	字符串	日志错误，忽略错误	座席尝试使用 X-Ray 段上下文但不存在时所采取的操作。	缺少上下文	通过亚马逊 Xray.策略. 上下文缺失策略	日志错误
守护者地址	字符串	格式化的 IP 地址和端口，或 TCP 和 UDP 地址列表	代理用于与 X-Ray 守护进程通信的地址。	AW_XRAY_ 守护门户地址	卓越亚马逊发射者守护者地址	127.0.0
TracingEgEgEgEgE	Boolean	TRUE、FALSE	启用通过 X-Ray 剂进行检测。	启用了 AW_XRAY 跟踪	通过卓越亚马逊 Xray.cn	TRUE
采样策略	字符串	中央, 本地, 无, 所有	代理使用的取样策略。ALL 捕获所有请求，NONE 不捕获任何请求。请参阅采样规则。	不适用	不适用	中央
跟踪注入前缀	字符串	任何字符串	在日志中注入跟踪 ID 之前包含提供的前缀。	不适用	不适用	无（空字符串）
采样规则清单	字符串	绝对文件路径	用作本地采样策略采样规则源的自定义采样规则文件的路径，或中央策略的备用规则。	不适用	不适用	默认采样规则 .JSON
Amazon 服务处理程序清单	字符串	绝对文件路径	自定义参数允许列表的路径，用于捕获来自Amazon开发工具包客户端。	不适用	不适用	默认参数白名单 .JSON
awsSdkVersion	整数	1、2	的版本Amazon适用于 Java 的开发工具包你正在使用如果忽略`awsServiceHandlerManifest`也没有设置。	不适用	不适用	2
最大堆栈跟踪	整数	非负带分数	要在跟踪中记录的堆栈跟踪的最大行数。	不适用	不适用	50
流阈值	整数	非负带分数	至少在关闭这么多的子段之后，它们被流式传输到带外守护程序，以避免块过大。	不适用	不适用	100
追踪注射	Boolean	TRUE、FALSE	启用 X-Ray 跟踪 ID 注入到日志中，如果日志记录也添加了。否则，什么也不做。	不适用	不适用	TRUE
插件	Boolean	TRUE、FALSE	启用用于记录有关Amazon您正在运行的环境。请参阅插件。	不适用	不适用	TRUE
collectSqlQueries	Boolean	TRUE、FALSE	以最大努力记录 SQL 子分段中的 SQL 查询字符串。	不适用	不适用	FALSE
上下文传播	Boolean	TRUE、FALSE	如果为 true，则自动在线程之间传播 X-Ray 上下文。否则，使用线程本地存储上下文，并且需要在线程之间进行手动传播。	不适用	不适用	TRUE

日志记录

X-Ray 代理的日志级别可以采用与适用于 Java 的 X-Ray SDK 相同的方式进行配置。请参阅Logging了解使用适用于 Java 的 X-Ray 开发工具包配置日志记录的详细信息。

手动检测

如果除了代理的自动检测外还要执行手动检测，请将 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.9.0</version> 
  </dependency> 
  </dependencies>

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


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

您可以添加自定义子分段以及批注、元数据和用户 ID，就像使用普通 SDK 一样。代理会自动跨线程传播上下文，因此在使用多线程应用程序时不需要传播上下文的任何解决方法。

Troubleshooting

由于代理提供全自动检测，因此在遇到问题时很难确定问题的根本原因。如果 X-Ray 代理未按预期工作，请查看以下问题和解决方案。X-Ray 代理和 SDK 使用雅加达共享日志记录 (JCL)，因此要查看日志记录输出，您需要确保将 JCL 连接到日志记录后端的桥在类路径上，例如log4j-jcl或者jcl-over-slf4j。

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

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

如果没有，请参阅X-Ray 守护程序来设置它。

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

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

在您的应用程序日志中，是否看到几条错误消息，说 “禁止Amazon X-Ray上下文缺少异常”？

出现这些错误的原因是代理正在尝试测量下游请求，如AmazonSDK 请求或 SQL 查询，但代理无法自动创建段。如果您看到许多这些错误，代理可能不是您的使用案例的最佳工具，您可能需要考虑使用 X-Ray SDK 进行手动检测。或者，您可以启用 X-Ray 开发工具包调试日志查看上下文缺少异常发生的堆栈跟踪。您可以用自定义段包装代码的这些部分，这应该能够解决这些错误。有关使用自定义分段包装下游请求的示例分析启动代码。

问题：我预计的某些区段不会出现在 X-Ray 控制台上

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

如果您希望创建的某些段没有出现在控制台中，则应用程序中的后台线程可能是原因。如果您的应用程序使用 “触发并忘记” 的后台 Lambda 程执行任务，例如使用AmazonSDK 或定期轮询某些 HTTP 端点，这可能会在代理跨线程传播上下文时混淆代理。要验证这是您的问题，请启用 X-Ray SDK 调试日志并检查以下消息：未发出命名 <NAME > 为正在进行的子段的父代的段。要变通解决此问题，您可以尝试在服务器返回之前加入后台线程，以确保记录其中完成的所有工作。或者，您可以将代理的contextPropagation配置false禁用后台线程中的上下文传播。如果你这样做，你将不得不使用自定义段手动测量这些线程，或忽略它们产生的缺少异常的上下文。

您是否已设置采样规则？

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

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

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

使用 Java

配置