适用于 Java 的AWS X-Ray SDK

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

SDK适用于 Java 的 X-Ray 是一个开源项目。你可以通过以下网址关注该项目并提交议题和拉取请求 GitHub：github.co m/aws/ aws-xray-sdk-java

首先通过添加AWSXRayServletFilter 作为 servlet 筛选器来跟踪传入请求。servlet 筛选器会创建分段。当分段处于打开状态时，您可以使用SDK客户端的方法向分段添加信息，并创建子分段来跟踪下游呼叫。SDK还会自动记录您的应用程序在区段打开时抛出的异常。

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

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

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

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

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

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

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

子模块

你可以从 Maven 下载SDK适用于 Java 的 X-Ray。X-R SDK ay for Java 按用例分为子模块，并附有版本管理材料清单：

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

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

要求

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

这SDK取决于编译和运行时的以下库：

这些依赖关系在pom.xml的文件中声明，SDK如果您使用 Maven 或 Gradle 进行构建，则会自动包含这些依赖关系。

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

依赖项管理

SDK适用于 Java 的 X-Ray 可从 Maven 获得：

如果您使用 Maven 来构建应用程序，请将SDK作为依赖项添加到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，请将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 的示例，请参阅示例应用程序。

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

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

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

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

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

X-Ray CloudWatch 指标

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

X 射线 CloudWatch 尺寸

使用下表中的维度来细化为装有 X-Ray 检测的Java应用程序返回的指标。

启用 X-Ray CloudWatch 指标

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