适用于 Java 的 AWS X-Ray 开发工具包 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

X-Ray SDK for Java是面向 Java Web 应用程序的一组库,提供用于生成跟踪数据并将其发送到 X-Ray 守护程序的类和方法。跟踪数据包括由应用程序提供服务的传入 HTTP 请求的相关信息,以及应用程序使用 AWS 开发工具包、HTTP 客户端或 SQL 数据库连接器对下游服务进行的调用。您还可以手动创建分段并在注释和元数据中添加调试信息。

注意

X-Ray SDK for Java 是一个开源项目。您可以跟踪该项目并在 GitHub 上提交问题和拉取请求:github.com/aws/aws-xray-sdk-java

首先通过添加AWSXRayServletFilter 作为 servlet 筛选器来跟踪传入请求。Servlet 筛选器创建一个分段。当分段打开时,您可以使用开发工具包客户端的方法将信息添加到分段,并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。

从版本 1.3 开始,您可以使用 Spring 中面向方面的编程 (AOP) 来分析应用程序。这意味着,您可以在应用程序运行于 AWS 上时分析应用程序,而无需向应用程序的运行时添加任何代码。

接下来,通过在生成配置中包含开发工具包 Instrumentor 子模块,使用X-Ray SDK for Java分析您的 AWS SDK for Java 客户端。当您使用分析过的客户端调用下游 AWS 服务或资源时,开发工具包会在子分段中记录有关调用的信息。您访问的 AWS 服务及其资源将在服务地图中显示为下游节点,帮助您标识单个连接上的错误和限制问题。

如果您不希望分析对 AWS 服务的所有下游调用,请将 Instrumentor 子模块留空并选择所要分析的客户端。通过添加 TracingHandler 到 AWS 开发工具包服务客户端来分析单个客户端。

其他 X-Ray SDK for Java 子模块为对 HTTP Web API 和 SQL 数据库的下游调用提供分析。您可以在 Apache HTTP 子模块中使用X-Ray SDK for Java版本的 HTTPClient 和 HTTPClientBuilder 来分析 Apache HTTP 客户端。要分析 SQL 查询,请将开发工具包的拦截程序添加到数据源

在开始使用开发工具包后,通过配置记录器和 servlet 筛选器来自定义其行为。您可以添加插件来记录有关应用程序上运行的计算资源的数据,通过定义采样规则来自定义采样行为,设置日志级别以在应用程序日志中查看来自开发工具包的更多或更少的信息。

记录有关请求以及应用程序在注释和元数据中所做的工作的其他信息。注释是简单的键值对,已为这些键值对编制索引以用于筛选条件表达式,以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低,并且可以记录整个对象和数组 — 可序列化为 JSON 的任何项目。

注释和元数据

注释和元数据是您用 X-Ray 开发工具包添加到分段中的任意文本。会对注释编制索引,用于与筛选表达式一同使用。不会对元数据编制索引,但是可以在原始分段中通过 X-Ray 控制台或 API 查看。您授予对 X-Ray 读取权限的人都可以查看此数据。

当代码中具有大量分析的客户端时,一个请求分段可包含大量子分段,分析的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在自定义子分段中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段,并记录子分段的元数据和注释,而不是编写父分段的所有内容。

子模块

您可以从 Maven 下载 X-Ray SDK for Java。X-Ray SDK for Java 按使用案例被拆分为子模块,其中的材料清单用于版本管理:

如果您使用 Maven 或 Gradle 来构建应用程序,则将X-Ray SDK for Java添加到您的构建配置中

有关开发工具包的类和方法的参考文档,请参阅适用于 Java API 的 AWS X-Ray 开发工具包参考

要求

X-Ray SDK for Java 需要 Java 8 或更高版本、Servlet API 3、AWS SDK 和 Jackson。

开发工具包在编译和运行时依赖于以下库:

  • 适用于 Java 的 AWS 开发工具包 1.11.398 版或更高版本

  • Servlet API 3.1.0

这些依赖项在开发工具包的 pom.xml 文件中声明,如果您使用 Maven 或 Gradle 生成则自动包括在内。

如果您使用包括在 X-Ray SDK for Java 中的库,则必须使用包括的版本。例如,如果您在运行时已经依赖于 Jackson 并在部署中为该依赖项包括了 JAR 文件,则必须删除这些 JAR 文件,因为开发工具包 JAR 包括其自己的 Jackson 库版本。

依赖项管理

X-Ray SDK for Java 可从 Maven 使用:

  • com.amazonaws

  • 构件aws-xray-recorder-sdk-bom

  • 版本2.4.0

如果您使用 Maven 来生成应用程序,则在 pom.xml 文件中添加开发工具包作为依赖项。

例 pom.xml - 依赖项

<dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-bom</artifactId> <version>2.4.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-core</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-apache-http</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId> </dependency> </dependencies>

对于 Gradle,添加开发工具包作为 build.gradle 文件中的编译时依赖项。

例 build.gradle - 依赖项

dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile("org.springframework.boot:spring-boot-starter-test") compile("com.amazonaws:aws-java-sdk-dynamodb") compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11") } dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.4.0') } }

如果您使用 Elastic Beanstalk 来部署应用程序,则可以使用 Maven 或 Gradle 在每次部署时生成 on-instance,而不是生成和上传包括所有依赖项的大档案。有关使用 Gradle 的示例,请参阅示例应用程序