适用于 Java 的 AWS X-Ray 自动分析代理 - AWS X-Ray
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 代理,请执行以下步骤。

  1. 在您的环境中运行 X-Ray 守护程序。有关更多信息,请参阅 X-Ray 守护程序

  2. 下载代理的最新分配解压缩存档,并记下存档在您的文件系统中的位置。其内容应与以下内容类似。

    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
  3. 修改应用程序的 JVM 参数以包含以下内容,这将启用代理。确保 -javaagent 参数位于 参数之前-jar(如果适用)。修改 JVM 参数的过程因用于启动 Java 服务器的工具和框架而异,因此请参阅服务器框架文档获取具体指导。

    -javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
  4. 要按 X-Ray 控制台上显示的内容指定应用程序的名称,请设置 AWS_XRAY_TRACING_NAME环境变量或 com.amazonaws.xray.strategy.tracingName系统属性。如果没有提供名称,则使用默认名称。

  5. 重新启动您的服务器或容器。现在可跟踪传入请求及其下游调用。如果您没有看到预期结果,请参阅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

字符串

绝对文件路径

要用作本地采样策略的采样规则或中心策略的回退规则源的自定义采样规则文件的路径。

不适用

不适用

DefaultSamplingRules.json

awsServiceHandlerManifest

字符串

绝对文件路径

自定义参数允许列表的路径,该列表从 AWS 开发工具包客户端捕获其他信息。

不适用

不适用

DefaultOperationParameterWhitelist.json

awsSdkVersion

整数

1、2

您正使用的适用于 Java 的 AWS 开发工具包的版本。如果未同时设置 awsServiceHandlerManifest,则忽略。

不适用

不适用

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-jcljcl-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 控制台上创建自定义采样规则,以相应地对所需的分段进行采样。有关更多信息,请参阅采样