本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS X-Ray 適用於 Java 的 SDK
**注意**
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
適用於 Java 的 X-Ray 開發套件是一組適用於 Java Web 應用程式的程式庫，提供產生追蹤資料並將其傳送至 X-Ray 協助程式的類別和方法。追蹤資料包含應用程式所服務傳入 HTTP 請求的相關資訊，以及應用程式使用 AWS SDK、HTTP 用戶端或 SQL 資料庫連接器對下游服務進行的呼叫。您也可以手動建立區段，並將除錯資訊新增至註釋和中繼資料中。
適用於 Java 的 X-Ray 開發套件是開放原始碼專案。您可以追蹤專案，並在 GitHub 上提交問題與提取請求：[github.com/aws/aws-xray-sdk-java](https://github.com/aws/aws-xray-sdk-java)
首先，[將 `AWSXRayServletFilter` 新增為 Servlet 篩選條件](xray-sdk-java-filters.md)以追蹤傳入的請求。servlet 篩選條件會建立[區段](xray-concepts.md#xray-concepts-segments)。當區段開啟時，您可以使用軟體開發套件用戶端的方法，將資訊新增到區段，並建立子區段以追蹤下游呼叫。軟體開發套件也會在區段為開啟時自動記錄應用程式擲回的例外狀況。
從 1.3 版開始，您可以使用 [Spring 的切面導向程式設計 (AOP)](xray-sdk-java-aop-spring.md) 來檢測應用程式。這表示您可以在應用程式執行時檢測應用程式 AWS，而無需將任何程式碼新增至應用程式的執行時間。
接著，使用適用於 Java 的 X-Ray 開發套件，透過在建置組態中[包含 SDK Instrumentor 子模組](#xray-sdk-java-dependencies) 適用於 Java 的 AWS SDK 來檢測用戶端。每當您使用經檢測的用戶端呼叫下游 AWS 服務 或資源時，開發套件會在子區段中記錄有關呼叫的資訊。而您在服務中存取 AWS 服務 的資源會在追蹤地圖上顯示為下游節點，以協助您識別錯誤並調節個別連線的問題。
如果您不想檢測所有下游呼叫 AWS 服務，您可以離開 Instrumentor 子模組，然後選擇要檢測的用戶端。透過[將 `TracingHandler`](xray-sdk-java-awssdkclients.md)新增至 AWS SDK 服務用戶端來檢測個別用戶端。
其他適用於 Java 的 X-Ray 開發套件子模組提供對 HTTP Web APIs和 SQL 資料庫進行下游呼叫的檢測。您可以在 Apache HTTP 子模組中使用[適用於 Java 的 X-Ray 開發套件 `HTTPClient`和 版本`HTTPClientBuilder`](xray-sdk-java-httpclients.md)來檢測 Apache HTTP 用戶端。若要檢測 SQL 查詢，請[將軟體開發套件的攔截程式新增至資料來源](xray-sdk-java-sqlclients.md)。
開始使用 SDK 之後，請透過[設定記錄器和 servlet 篩選條件來](xray-sdk-java-configuration.md)自訂其行為。您可以新增外掛程式，以記錄執行應用程式所需的運算資源相關資料、定義抽樣規則以自訂抽樣行為，並設定日誌層級以在應用程式日誌中查看更多或更少的軟體開發套件資訊。
使用[註釋與中繼資料](xray-sdk-java-segment.md)，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於[篩選條件表達式](xray-console-filters.md)，因此您可以搜尋包含特定資料的追蹤。中繼資料項目的限制性較低，可以記錄整個物件和陣列，任何可以序列化為 JSON 的項目。
**標註與中繼資料**
註釋和中繼資料是您使用 X-Ray 開發套件新增至客群的任意文字。註釋會編製索引，以便與篩選條件表達式搭配使用。中繼資料不會編製索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授予 X-Ray 讀取存取權的任何人都可以檢視此資料。
當程式碼中有許多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在[自訂子區段](xray-sdk-java-subsegments.md)中，以組織和群組子區段。您可以為整個函數或任何部分的程式碼建立自訂子區段，並記錄子區段上的中繼資料和註釋，而不必寫入父區段上的所有項目。
## 子模組
您可以從 Maven 下載適用於 Java 的 X-Ray 開發套件。適用於 Java 的 X-Ray 開發套件會依使用案例分割為子模組，其中包含版本管理的物料清單：
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/) （必要） – 用於建立客群和傳輸客群的基本功能。包含 `AWSXRayServletFilter` 以檢測傳入的請求。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/) – 將追蹤 適用於 Java 的 AWS SDK 用戶端新增為請求處理常式，以檢測對用戶端 AWS 服務 發出的呼叫。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/) – 透過新增追蹤用戶端做為請求攔截器，檢測對 適用於 Java 的 AWS SDK 2.2 和更新版本的用戶端 AWS 服務 發出的呼叫。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/) – 使用 `aws-xray-recorder-sdk-aws-sdk`， 會自動檢測所有 適用於 Java 的 AWS SDK 用戶端。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/) – 使用 `aws-xray-recorder-sdk-aws-sdk-v2`時，會自動檢測所有 適用於 Java 的 AWS SDK 2.2 和更新版本的用戶端。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/) – 檢測使用 Apache HTTP 用戶端進行的傳出 HTTP 呼叫。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/) – 為 Spring AOP Framework 應用程式提供攔截器。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/) – 檢測使用 JDBC 對 PostgreSQL 資料庫發出的外撥呼叫。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/) – 檢測對使用 JDBC 進行之 MySQL 資料庫的傳出呼叫。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/) – 提供物料清單，可用來指定用於所有子模組的版本。
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/) – 從收集的 X-Ray 區段發佈未取樣的 Amazon CloudWatch 指標。
如果您使用 Maven 或 Gradle 建置應用程式，[請將適用於 Java 的 X-Ray 開發套件新增至建置組態](#xray-sdk-java-dependencies)。
如需 SDK 類別和方法的參考文件，請參閱適用於 [AWS X-Ray Java 的 SDK API 參考](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc)。
## 要求
適用於 Java 的 X-Ray 開發套件需要 Java 8 或更新版本、Servlet API 3、 AWS SDK 和 Jackson。
軟體開發套件在編譯和執行時間需仰賴下列程式庫：
+ AWS 適用於 Java 的 SDK 1.11.398 版或更新版本
+ Servlet API 3.1.0
軟體開發套件的 `pom.xml` 檔案中有宣告這些相依性。如果您使用 Maven 或 Gradle 來建置，則會自動包含這些相依性。
如果您使用的程式庫包含在適用於 Java 的 X-Ray 開發套件中，則必須使用隨附的版本。例如，如果您已在執行時間相依於 Jackson 並為了該相依性在部署中包含 JAR 檔案，則必須移除這些 JAR 檔案，因為軟體開發套件 JAR 包含自己的 Jackson 程式庫版本。
## 相依性管理
適用於 Java 的 X-Ray 開發套件可從 Maven 取得：
+ **群組** – `com.amazonaws`
+ **成品** – `aws-xray-recorder-sdk-bom`
+ **版本**：`2.11.0`
如果您使用 Maven 來建置應用程式，請在 `pom.xml` 檔案中，將軟體開發套件新增為依存項目。
**Example pom.xml - 依存項目**
```
com.amazonaws
aws-xray-recorder-sdk-bom
2.11.0
pom
import
com.amazonaws
aws-xray-recorder-sdk-core
com.amazonaws
aws-xray-recorder-sdk-apache-http
com.amazonaws
aws-xray-recorder-sdk-aws-sdk
com.amazonaws
aws-xray-recorder-sdk-aws-sdk-instrumentor
com.amazonaws
aws-xray-recorder-sdk-sql-postgres
com.amazonaws
aws-xray-recorder-sdk-sql-mysql
```
若是 Gradle，請在 `build.gradle` 檔案中，將軟體開發套件新增為編譯時間依存項目。
**Example 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 的範例，請參閱[範例應用程式](xray-scorekeep.md)。
## AWS X-Ray 適用於 Java 的 X-Ray 開發套件的 指標
**注意**
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
本主題說明 AWS X-Ray 命名空間、指標和維度。您可以使用適用於 Java 的 X-Ray 開發套件，從收集的 X-Ray 區段發佈未取樣的 Amazon CloudWatch 指標。這些指標衍生自區段的開始和結束時間，以及錯誤、故障和節流狀態標記。您可以使用這些追蹤指標，公開子區段內的重試和相依性問題。
CloudWatch 是指標儲存庫。指標是 CloudWatch 中的基本概念，代表一組按時間排序的資料點。您 （或 AWS 服務) 將指標資料點發佈至 CloudWatch，並擷取有關這些資料點的統計資料，做為一組循序的時間序列資料。
指標是由名稱、命名空間和一個或多個維度做唯一的定義。每個資料點都有時間戳記和可選的測量單位。當您請求統計資料時，傳回的資料流是藉由命名空間、指標名稱和維度做識別。
如需有關 CloudWatch 的詳細資訊，請參閱《[https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/)》。
### X-Ray CloudWatch 指標
`ServiceMetrics/SDK` 命名空間包含下列指標。
| 指標 | 統計資訊可用 | Description | 單位 |
| --- | --- | --- | --- |
| `Latency` | 平均、最小、最大、計數 | 開始與結束時間之間的差異。平均、最小和最大皆描述操作延遲。計數描述呼叫計數。 | 毫秒 |
| `ErrorRate` | 平均數、總和 | 失敗原因為 `4xx Client Error` 狀態碼的請求速率，導致錯誤。 | 百分比 |
| `FaultRate` | 平均數、總和 | 失敗原因為 `5xx Server Error` 狀態碼的追蹤速率，導致故障。 | 百分比 |
| `ThrottleRate` | 平均數、總和 | 傳回 `429` 狀態碼的節流追蹤速率。這是 `ErrorRate` 指標的一部分。 | 百分比 |
| `OkRate` | 平均數、總和 | 產生 `OK` 狀態碼的追蹤請求速率。 | 百分比 |
### X-Ray CloudWatch 維度
使用下表中的維度來精簡針對 X-Ray 檢測Java應用程式傳回的指標。
| 維度 | Description |
| --- | --- |
| `ServiceType` | 如不清楚，即為服務的類型，例如，`AWS::EC2::Instance` 或 `NONE`。 |
| `ServiceName` | 服務的正式名稱。 |
### 啟用 X-Ray CloudWatch 指標
使用下列程序在經檢測Java的應用程式中啟用追蹤指標。
**設定追蹤指標**
1. 新增`aws-xray-recorder-sdk-metrics`套件做為Apache Maven相依性。如需詳細資訊，請參閱[適用於 Java 子模組的 X-Ray 開發套件](#xray-sdk-java-submodules)。
1. 啟用新的 `MetricsSegmentListener()` 做為全域記錄器組建的一部分。
**Example src/com/myapp/web/Startup.java**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard()
.withPlugin(new EC2Plugin())
.withPlugin(new ElasticBeanstalkPlugin())
.withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
1. 部署 CloudWatch 代理程式以使用 Amazon Elastic Compute Cloud (Amazon EC2)、Amazon Elastic Container Service (Amazon ECS) 或 Amazon Elastic Kubernetes Service (Amazon EKS) 收集指標：
+ 若要設定 Amazon EC2，請參閱[安裝 CloudWatch 代理程式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html)。
+ 若要設定 Amazon ECS，請參閱[使用 Container Insights 監控 Amazon ECS 容器](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html)。
+ 若要設定 Amazon EKS，請參閱[使用 Amazon CloudWatch 可觀測性 Amazon CloudWatch 代理](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html)程式。
1. 設定 SDK 以與 CloudWatch 代理程式通訊。根據預設，軟體開發套件會與地址 上的 CloudWatch 代理程式通訊`127.0.0.1`。您可以將環境變數或 Java 屬性設為 `address:port`，以設定替代位址。
**Example 環境變數**
```
AWS_XRAY_METRICS_DAEMON_ADDRESS={{address:port}}
```
**Example Java 屬性**
```
com.amazonaws.xray.metrics.daemonAddress={{address:port}}
```
**驗證組態**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 開啟 **Metrics (指標)** 標籤，以觀察指標的湧入。
1. （選用） 在 CloudWatch 主控台的**日誌**索引標籤上，開啟`ServiceMetricsSDK`日誌群組。尋找符合主機指標的日誌資料流，並確認日誌訊息。