Amazon X-Ray SDK for Java - Amazon X-Ray
子模块要求依赖项管理
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon X-Ray SDK for Java

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

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

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

从 1.3 版开始，您可以使用春季面向方面的编程（AOP）. 这意味着，您可以在应用程序运行时分析应用程序。Amazon，而无需向应用程序的运行时添加任何代码。

接下来，使用适用于 Java 的 X-Ray 开发工具包来分析Amazon SDK for Java按客户端包括 SDK 仪器子模块在你的构建配置中。每当你打电话给下游Amazon具有分析的客户端的服务或资源时，开发工具包在子分段中记录有关调用的信息。Amazon您访问的 服务及其资源将在服务地图中显示为下游节点，帮助您标识单个连接上的错误和限制问题。

如果你不想仪器所有下游呼叫Amazon服务，您可以将 Instruments 子模块留空并选择要分析的客户端。仪器个人客户添加TracingHandler到AmazonSDK 服务客户端。

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

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

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

注释和元数据

注释和元数据是您使用 X-Ray 开发工具包添加到分段中的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始区段中查看。任何你授予对 X-Ray 的读取权限的人都可以查看这些数据。

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

子模块

您可以从 Maven 下载适用于 Java 的 X-Ray 开发工具包。适用于 Java 的 X-Ray 开发工具包按使用案例被拆分为子模块，其中的材料清单用于版本管理：

如果您使用 Maven 或 Gradle 来构建应用程序，将适用于 Java 的 X-Ray 软件开发工具包添加到您.

有关开发工具包的类和方法的参考文档，请参阅Amazon X-Ray适用 SDK for Java API 参考.

要求

适用于 Java 的 X-Ray 开发工具包需要 Java 8 或更高版本、Servlet API 3、AmazonSDK 和杰克逊。

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

  • AmazonSDK for Java 1.11.398 版或更高版本

  • Servlet API 3.1.0

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

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

依赖项管理

适用于 Java 的 X-Ray 开发工具包可从 Maven 使用：

  • Group–com.amazonaws

  • Artifact–aws-xray-recorder-sdk-bom

  • 版本–2.11.0

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

例 pom.xml - 依赖项
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.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.11.0')
    }
}

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