本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
适用于 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主页
示例应用程序
eb-java-scorekeep 示例应用程序已调整为使用 代理进行检测。
开始使用
要在您自己的应用程序中开始使用 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
代理由用户提供的外部 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 文档。所有字段都是可选字段。
属性名称 | Type | 有效值 | 描述 | 环境变量 | 系统属性 | 默认值 |
---|---|---|---|---|---|---|
serviceName |
字符串 |
任何字符串 |
您的已分析服务在 X-Ray 控制台中显示的名称。 |
AWS_XRAY_TRACING_NAME |
com.amazonaws.xray.strategy.tracingName |
XRayInstrumentedService |
contextMissingStrategy |
字符串 |
LOG_ERROR、IGNORE_ERROR |
代理尝试使用 X-Ray 分段上下文但不存在时执行的操作。 |
AWS_XRAY_CONTEXT_MISSING |
com.amazonaws.xray.strategy.contextMissingStrategy |
日志错误 |
daemonAddress |
字符串 |
已设置格式的 IP 地址和端口,或者 TCP 和 UDP 地址列表 |
代理用来与 X-Ray 守护程序通信的地址。 |
AWS_XRAY_DAEMON_ADDRESS |
com.amazonaws.xray.emitter.daemonAddress |
127.0.0.1:2000 |
tracingEnabled |
Boolean |
True、False |
由 X-Ray 代理启用分析。 |
AWS_XRAY_TRACING_ENABLED |
com.amazonaws.xray.tracingEnabled |
TRUE |
samplingStrategy |
字符串 |
CENTRAL、LOCAL、NONE、ALL |
代理使用的采样策略。ALL 捕获所有请求,NONE 不捕获任何请求。请参阅采样规则。 |
不适用 |
不适用 |
中央 |
traceIdInjectionPrefix |
字符串 |
任何字符串 |
在 日志中注入跟踪 IDs 之前包含提供的前缀。 |
不适用 |
不适用 |
无(空字符串) |
samplingRulesManifest |
字符串 |
绝对文件路径 |
要用作本地采样策略的采样规则或中心策略的回退规则源的自定义采样规则文件的路径。 |
不适用 |
不适用 |
|
|
字符串 |
绝对文件路径 |
自定义参数允许列表的路径,该列表从 AWS 开发工具包客户端捕获其他信息。 |
不适用 |
不适用 |
|
awsSdkVersion |
整数 |
1、2 |
您正使用的适用于 Java 的 AWS 开发工具包的版本。如果未同时设置 |
不适用 |
不适用 |
2 |
maxStackTraceLength |
整数 |
非负整数 |
要在跟踪中记录的堆栈跟踪的最大行。 |
不适用 |
不适用 |
50 |
streamingThreshold |
整数 |
非负整数 |
关闭至少此数量的子分段后,它们将流式传输到守护程序带外 以避免数据块太大。 |
不适用 |
不适用 |
100 |
traceIdInjection |
Boolean |
True、False |
如果还添加了X-Ray日志记录配置中描述的依赖项和配置,则启用将 跟踪 ID 注入日志的功能。否则, 将不执行任何操作。 |
不适用 |
不适用 |
TRUE |
pluginsEnabled |
Boolean |
True、False |
启用可记录有关您在其中执行操作的 AWS 环境的元数据的插件。请参阅插件。 |
不适用 |
不适用 |
TRUE |
collectSqlQueries |
Boolean |
True、False |
在 SQL 子分段中记录尽力的 SQL 查询字符串。 |
不适用 |
不适用 |
FALSE |
contextPropagation |
Boolean |
True、False |
如果为 true,则在线程之间自动传播 X-Ray 上下文。否则,使用 Thread Local 存储上下文,并且需要跨线程手动传播。 |
不适用 |
不适用 |
TRUE |
手动分析
如果您希望在代理的自动分析之外执行手动分析,请将 X-Ray 开发工具包作为依赖项添加到您的项目中。请注意,跟踪传入请求中提到的开发工具包的自定义 servlet 筛选器与 X-Ray 代理不兼容。
您必须使用最新版本的 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 控制台上创建自定义采样规则,以相应地对所需的分段进行采样。有关更多信息,请参阅采样。