Amazon X-Ray 适用于 Java 的 SDK

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

X-Ray SDK for Java 是一个开源项目。你可以关注该项目并在 github 上 GitHub提交议题和拉取请求。 com/aws/aws-xray-sdk-java

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

从版本 1.3 开始，您可以使用 Spring 中的面向方面的编程 (AOP) 来检测应用程序。这意味着你可以在应用程序运行时对其进行检测，而无需在 Amazon应用程序的运行时中添加任何代码。

接下来，使用适用于 Java 的 X-Ray SDK，在构建配置中包含 SDK Instrumentor 子模块，对 Amazon SDK for Java 客户进行检测。每当您使用已检测的客户端调用下游 Amazon Web Services 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 Amazon Web Services 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。

如果您不想检测所有下游调用 Amazon Web Services 服务，则可以省略 Instrumentor 子模块，然后选择要检测的客户端。通过向 Amazon SDK 服务客户端添加TracingHandler来检测各个客户端。

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

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

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

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

子模块

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

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

有关 SDK 的类和方法的参考文档，请参阅Amazon X-Ray SDK for Java API 参考。

要求

适用于 Java 的 X-Ray SDK 需要 Java 8 或更高版本、Servlet API 3、 Amazon SDK 和 Jackson。

该 SDK 在编译和运行时依赖于以下库：

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

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

依赖关系管理

可从 Maven 获得 X-Ray SDK for Java：

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

<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，添加 SDK 作为 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 在每次部署时生成 on-instance，而不是生成和上传包括所有依赖项的大档案。有关使用 Gradle 的示例，请参阅示例应用程序。

Amazon X-Ray 适用于 Java 的 X-Ray SDK 的指标

本主题介绍 Amazon X-Ray 命名空间、指标和维度。您可以使用适用于 Java 的 X-Ray SDK 从您收集的 X-Ray 细分中发布未采样的亚马逊 CloudWatch 指标。这些指标来自分段的开始和结束时间以及错误、故障和限制状态标志。使用这些指标可暴露子分段里的重试和依赖项问题。

CloudWatch 是一个指标存储库。指标是中的基本概念 CloudWatch ，代表一组按时间排序的数据点。您（或 Amazon Web Services 服务）将指标数据点发布到其中， CloudWatch 并将有关这些数据点的统计数据作为一组有序的时间序列数据进行检索。

指标通过名称、命名空间以及一个或多个维度进行唯一定义。每个数据点都有一个时间戳和一个可选的度量单位。当请求统计数据时，返回的数据流根据命名空间、指标名称和维度加以识别。

有关的更多信息 CloudWatch，请参阅 Amazon CloudWatch 用户指南。

X-Ray CloudWatch 指标

ServiceMetrics/SDK 命名空间包括以下指标。

X 射线 CloudWatch 尺寸

您可以用下表中的维度来优化针对经 X-Ray 检测的 Java 应用程序返回的指标。

启用 X-Ray CloudWatch 指标

使用以下过程在已检测的 Java 应用程序中启用跟踪指标。