本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 開發套件/協助程式維護通知 – 在 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 的 AWS X-Ray 自動檢測代理程式是一種追蹤解決方案，能以最少的開發工作來檢測您的 Java Web 應用程式。代理程式可追蹤 servlet 型應用程式，以及使用支援的架構和程式庫提出的所有代理程式下游請求。這包括下游 Apache HTTP 請求、 AWS SDK 請求，以及使用 JDBC 驅動程式進行的 SQL 查詢。代理程式會跨執行緒傳播 X-Ray 內容，包括所有作用中區段和子區段。X-Ray 開發套件的所有組態和多樣性仍可與 Java 代理程式搭配使用。已選擇適當的預設值，以確保代理程式以最少的努力運作。 X-Ray 代理程式解決方案最適合以 servlet 為基礎的請求回應 Java Web 應用程式伺服器。如果您的應用程式使用非同步架構，或未妥善建模為請求回應服務，建議您改為考慮使用 SDK 手動檢測。  X-Ray 代理程式是使用分散式系統理解工具組或 DiSCo 建置。DiSCo 是一種開放原始碼架構，用於建置可在分散式系統中使用的 Java 代理程式。雖然您不需要了解 DiSCo 是否使用 X-Ray 代理程式，但您可以前往 [ GitHub 上的專案首頁](https://github.com/awslabs/disco)，進一步了解專案。X-Ray 代理程式也是完全開放原始碼。若要檢視原始程式碼、做出貢獻或引發有關代理程式的問題，請造訪 [ GitHub 上的儲存庫](https://github.com/aws/aws-xray-java-agent)。 ## 範例應用程式 [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent) 範例應用程式已調整為使用 X-Ray 代理程式進行檢測。此分支不包含 servlet 篩選條件或記錄器組態，因為這些函數是由代理程式完成。若要在本機或使用 AWS 資源執行應用程式，請遵循範例應用程式讀我檔案的步驟。使用範例應用程式產生 X-Ray 追蹤的指示，請參閱 [範例應用程式的教學](xray-scorekeep.md)課程。 ## 開始使用 若要在您自己的應用程式中開始使用 X-Ray 自動檢測 Java 代理程式，請遵循下列步驟。 1. 在您的環境中執行 X-Ray 協助程式。如需詳細資訊，請參閱[AWS X-Ray 協助程式](xray-daemon.md)。 1. 下載 [代理程式的最新分佈](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip)。解壓縮封存，並記下其在檔案系統中的位置。其內容看起來應該如下所示。 ``` disco ├── disco-java-agent.jar └── disco-plugins     ├── aws-xray-agent-plugin.jar     ├── disco-java-agent-aws-plugin.jar     ├── disco-java-agent-sql-plugin.jar     └── disco-java-agent-web-plugin.jar ``` 1. 修改應用程式的 JVM 引數，以包含下列項目，以啟用代理程式。如果適用，請確定`-javaagent`引數放在`-jar`引數*前面*。修改 JVM 引數的程序會根據您用來啟動 Java 伺服器的工具和架構而有所不同。如需特定指引，請參閱伺服器架構的文件。 ``` -javaagent://disco-java-agent.jar=pluginPath=//disco-plugins ``` 1. 若要指定應用程式名稱在 X-Ray 主控台上顯示的方式，請設定`AWS_XRAY_TRACING_NAME` 環境變數或`com.amazonaws.xray.strategy.tracingName` 系統屬性。如果未提供名稱，則會使用預設名稱。 1. 重新啟動您的伺服器或容器。現在會追蹤傳入的請求及其下游呼叫。如果您沒有看到預期結果，請參閱 [疑難排解](#XRayAutoInstrumentationAgent-Troubleshooting)。 ## Configuration X-Ray 代理程式是由外部使用者提供的 JSON 檔案所設定。根據預設，此檔案位於名為 的使用者 classpath 根目錄 （例如，在其`resources` 目錄中） `xray-agent.json`。您可以設定組態檔案的自訂位置，方法是將`com.amazonaws.xray.configFile`系統屬性設定為組態檔案的絕對檔案系統路徑。 接著會顯示範例組態檔案。 ``` {         "serviceName": "XRayInstrumentedService",     "contextMissingStrategy": "LOG_ERROR",     "daemonAddress": "127.0.0.1:2000",     "tracingEnabled": true,     "samplingStrategy": "CENTRAL",         "traceIdInjectionPrefix": "prefix",         "samplingRulesManifest": "/path/to/manifest",         "awsServiceHandlerManifest": "/path/to/manifest",         "awsSdkVersion": 2,         "maxStackTraceLength": 50,         "streamingThreshold": 100,         "traceIdInjection": true,         "pluginsEnabled": true,         "collectSqlQueries": false } ``` ### 組態規格 下表說明每個屬性的有效值。屬性名稱區分大小寫，但其金鑰不區分大小寫。對於可由環境變數和系統屬性覆寫的屬性，優先順序一律是環境變數、系統屬性，然後是組態檔案。如需您可以覆寫之屬性的相關資訊，請參閱 [環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)。所有欄位都是選擇性的。 | 屬性名稱 | Type | 有效值 | Description | 環境變數 | 系統屬性 | 預設 | | --- | --- | --- | --- | --- | --- | --- | | serviceName | String | 任何字串 | 檢測服務的名稱會顯示在 X-Ray 主控台中。 | AWS\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService | | contextMissingStrategy | String | LOG\$1ERROR、IGNORE\$1ERROR | 當代理程式嘗試使用 X-Ray 區段內容但不存在時所採取的動作。 | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.strategy.contextMissingStrategy | LOG\$1ERROR | | daemonAddress | String | 格式化 IP 地址和連接埠，或 TCP 和 UDP 地址清單 | 代理程式用來與 X-Ray 協助程式通訊的地址。 | AWS\$1XRAY\$1DAEMON\$1ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1：2000 | | tracingEnabled | Boolean | True、False | 啟用 X-Ray 代理程式的檢測。 | AWS\$1XRAY\$1TRACING\$1ENABLED | com.amazonaws.xray.tracingEnabled | TRUE | | samplingStrategy | String | CENTRAL、LOCAL、NONE、ALL | 代理程式使用的抽樣策略。ALL 會擷取所有請求，NONE 不會擷取任何請求。請參閱[取樣規則](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling)。 | N/A | N/A | 中部 | | traceIdInjectionPrefix | String | 任何字串 | 在日誌中包含注入追蹤 IDs前提供的字首。 | N/A | N/A | 無 （空字串） | | samplingRulesManifest | String | 絕對檔案路徑 | 自訂抽樣規則檔案的路徑，做為本機抽樣策略的抽樣規則來源，或中央策略的備用規則。 | N/A | N/A | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) | | awsServiceHandlerManifest | String | 絕對檔案路徑 | 自訂參數允許清單的路徑，該清單會從 AWS SDK 用戶端擷取其他資訊。 | N/A | N/A | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) | | awsSdkVersion | Integer | 1、2 | 您正在使用的[AWS 適用於 Java 的開發套件](https://docs.aws.amazon.com/sdk-for-java/index.html)版本。如果 也未設定`awsServiceHandlerManifest` ，則忽略。 | N/A | N/A | 2 | | maxStackTraceLength | Integer | 非負整數 | 要在追蹤中記錄的堆疊追蹤行數上限。 | N/A | N/A | 50 | | streamingThreshold | Integer | 非負整數 | 至少關閉此多個子區段後，它們會串流到out-of-band協助程式，以避免區塊過大。 | N/A | N/A | 100 | | traceIdInjection | Boolean | True、False | 如果記錄組態中 [描述的相依性和組態也新增，則啟用 X-Ray 追蹤 ID 注入日誌](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) 。否則， 不會執行任何動作。 | N/A | N/A | TRUE | | pluginsEnabled | Boolean | True、False | 啟用可記錄您所操作 AWS 環境中繼資料的外掛程式。請參閱 [外掛程式](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins)。 | N/A | N/A | TRUE | | collectSqlQueries | Boolean | True、False | 盡最大努力在 SQL 子區段中記錄 SQL 查詢字串。 | N/A | N/A | FALSE | | contextPropagation | Boolean | True、False | 如果為 true，在執行緒之間自動傳播 X-Ray 內容。否則， 會使用 Thread Local 來存放內容，而且需要跨執行緒手動傳播。 | N/A | N/A | TRUE | ### 記錄組態 X-Ray 代理程式的日誌層級的設定方式與適用於 Java 的 X-Ray 開發套件相同。[日誌](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) 如需使用適用於 Java 的 X-Ray 開發套件設定記錄的詳細資訊，請參閱 。 ### 手動檢測 如果您想要在代理程式的自動檢測之外執行手動檢測，請將 X-Ray 開發套件新增為專案的相依性。請注意，[追蹤傳入請求](xray-sdk-java-filters.md)中提到的 SDK 自訂 servlet 篩選條件與 X-Ray 代理程式不相容。 **注意** 您必須使用最新版本的 X-Ray 開發套件來執行手動檢測，同時使用 代理程式。 如果您在 Maven 專案中工作，請將下列相依性新增至您的 `pom.xml` 檔案。 ```       com.amazonaws     aws-xray-recorder-sdk-core     2.11.0      ``` 如果您在 Gradle 專案中工作，請將下列相依性新增至您的 `build.gradle` 檔案。 ``` implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' ``` 除了[註釋、中繼資料和使用者 IDs](xray-sdk-java-segment.md) 之外，您還可以在使用代理程式時新增[自訂子區段](xray-sdk-java-subsegments.md)，就像使用一般 SDK 一樣。代理程式會自動跨執行緒傳播內容，因此在使用多執行緒應用程式時，不需要傳播內容的解決方法。 ## 疑難排解 由於代理程式提供全自動檢測，當您遇到問題時，可能很難識別問題的根本原因。 如果 X-Ray 代理程式無法如預期般運作，請檢閱下列問題和解決方案。X-Ray 代理程式和 SDK 使用 Jakarta Commons Logging (JCL)。若要查看記錄輸出，請確定將 JCL 連接至記錄後端的橋接器位於 classpath 上，如下列範例所示： `log4j-jcl`或 `jcl-over-slf4j`。 ### 問題：我在應用程式上已啟用 Java 代理程式，但在 X-Ray 主控台上看不到任何內容 **X-Ray 協助程式是否在同一部機器上執行？** 如果沒有，請參閱 [X-Ray 協助程式文件](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) 進行設定。 **在您的應用程式日誌中，您是否看到像是「初始化 X-Ray 代理程式記錄器」的訊息？** 如果您已將代理程式正確新增至應用程式，則此訊息會在應用程式啟動時記錄於 INFO 層級，然後再開始接收請求。如果此訊息不存在，則 Java 代理程式不會與 Java 程序一起執行。請確定您已正確遵循所有設定步驟，且沒有錯字。 **在您的應用程式日誌中，您是否看到多個錯誤訊息，指出像是「隱藏 AWS X-Ray 內容缺少例外狀況」？** 這些錯誤是因為代理程式嘗試檢測下游請求，例如 AWS SDK 請求或 SQL 查詢，但代理程式無法自動建立客群。如果您看到其中許多錯誤，代理程式可能不是適合您使用案例的最佳工具，建議您改為考慮使用 X-Ray SDK 進行手動檢測。或者，您可以啟用 X-Ray SDK [偵錯日誌](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)，以查看發生內容遺失例外狀況的堆疊追蹤。您可以使用自訂區段包裝程式碼的這些部分，這應該會解決這些錯誤。如需使用自訂區段包裝下游請求的範例，請參閱 [檢測啟動程式碼中的範例程式碼](scorekeep-startup.md)。 ### 問題：我預期的某些區段不會出現在 X-Ray 主控台上 **您的應用程式是否使用多執行緒？** 如果您預期建立的某些客群未出現在主控台中，則應用程式中的背景執行緒可能是原因。如果您的應用程式使用「觸發並忘記」的背景執行緒來執行任務，例如使用 AWS SDK 對 Lambda 函數進行一次性呼叫，或定期輪詢一些 HTTP 端點，這可能會在代理程式跨執行緒傳播內容時混淆代理程式。若要驗證這是您的問題，請啟用 X-Ray SDK 偵錯日誌，並檢查是否有訊息，例如：*未發出名為 的區段，因為其父系正在進行的子區段*。若要解決此問題，您可以在伺服器返回之前嘗試加入背景執行緒，以確保記錄其中完成的所有工作。或者，您可以將代理程式的`contextPropagation`組態設定為 `false`，以停用背景執行緒中的內容傳播。如果您這樣做，您必須使用自訂區段手動檢測這些執行緒，或忽略其產生的缺少內容例外狀況。 **您是否已設定抽樣規則？** 如果 X-Ray 主控台上似乎出現隨機或非預期的區段，或您預期在主控台上的區段未出現，您可能會遇到抽樣問題。X-Ray 代理程式會使用 X-Ray 主控台的規則，將集中式取樣套用至其建立的所有區段。預設規則是每秒 1 個區段，加上之後 5% 的區段進行取樣。這表示可能無法取樣使用代理程式快速建立的區段。若要解決此問題，您應該在 X-Ray 主控台上建立自訂取樣規則，以適當取樣所需的區段。如需詳細資訊，請參閱[取樣](xray-console-sampling.md)。 # 設定適用於 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)。 適用於 Java 的 X-Ray 開發套件包含名為 的類別`AWSXRay`，可提供全域記錄器。這是可以用來檢測程式碼的 `TracingHandler`。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的 `AWSXRayServletFilter`。 **Topics** + [服務外掛程式](#xray-sdk-java-configuration-plugins) + [抽樣規則](#xray-sdk-java-configuration-sampling) + [日誌](#xray-sdk-java-configuration-logging) + [區段接聽程式](#xray-sdk-java-configuration-listeners) + [環境變數](#xray-sdk-java-configuration-envvars) + [系統屬性](#xray-sdk-java-configuration-sysprops) ## 服務外掛程式 使用 `plugins` 記錄託管您應用程式之服務的相關資訊。 **外掛程式** + Amazon EC2 – `EC2Plugin` 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。 + Elastic Beanstalk – `ElasticBeanstalkPlugin` 新增環境名稱、版本標籤和部署 ID。 + Amazon ECS – `ECSPlugin` 新增容器 ID。 + Amazon EKS – `EKSPlugin` 新增容器 ID、叢集名稱、Pod ID 和 CloudWatch Logs 群組。 ![\[使用 Amazon EC2 和 Elastic Beanstalk 外掛程式來分割資源資料。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) 若要使用外掛程式，請在 `AWSXRayRecorderBuilder` 上呼叫 `withPlugin`。 **Example src/main/java/scorekeep/WebConfig.java - 記錄器** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` 軟體開發套件也會使用外掛程式設定來設定區段上的 `origin` 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時，開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。 ## 抽樣規則 SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來判斷要記錄哪些請求。預設規則每秒追蹤第一個請求，以及傳送追蹤到 X-Ray 的所有服務中任何額外請求的 5%。[在 X-Ray 主控台中建立其他規則](xray-console-sampling.md)，以自訂為每個應用程式記錄的資料量。 軟體開發套件會依照自訂規則的定義順序進行套用。如果請求符合多個自訂規則，軟體開發套件只會套用第一個規則。 **注意** 如果開發套件無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可，或無法連接到 X-Ray 協助程式，該常駐程式充當 SDK 進行 API 呼叫的 TCP 代理，則可能會發生這種情況。 您也可以設定 SDK 從 JSON 文件載入抽樣規則。開發套件可以在 X-Ray 取樣無法使用的情況下，使用本機規則做為備份，或僅使用本機規則。 **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` 此範例會定義一個自訂規則和預設規則。自訂規則會套用 5% 的取樣率，沒有追蹤 下路徑的最低請求數`/api/move/`。預設規則會追蹤每秒的第一個請求和 10% 的額外請求。 在本機定義規則的缺點是，固定目標是由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。 在 上 AWS Lambda，您無法修改取樣率。如果您的函數是由 檢測服務呼叫，則 Lambda 將記錄產生該服務取樣之請求的呼叫。如果啟用主動追蹤且不存在追蹤標頭，Lambda 會做出抽樣決策。 若要在 Spring 中提供備份規則，請在組態類別中使用 `CentralizedSamplingStrategy` 設定全域記錄器： **Example src/main/java/myapp/WebConfig.java - 記錄器組態** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } ``` 若是 Tomcat，請新增接聽程式以擴展 `ServletContextListener`，並在部署描述項中註冊接聽程式。 **Example src/com/myapp/web/Startup.java** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` 若僅要使用本機規則，請將 `CentralizedSamplingStrategy` 取代為 `LocalizedSamplingStrategy`。 ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## 日誌 根據預設，軟體開發套件會將 `ERROR`層級的訊息輸出到您的應用程式日誌。您可以在 SDK 上啟用偵錯層級記錄，將更詳細的日誌輸出到您的應用程式日誌檔案。有效的日誌層級為 `DEBUG`、`INFO`、`ERROR`、 `WARN`和 `FATAL`。`FATAL`日誌層級會靜音所有日誌訊息，因為 SDK 不會在嚴重層級記錄。 **Example application.properties** 使用 `logging.level.com.amazonaws.xray` 屬性設定記錄日誌層級。 ``` logging.level.com.amazonaws.xray = DEBUG ``` 當您[手動產生子區段](xray-sdk-java-subsegments.md)時，可使用除錯日誌來識別問題，例如未結束的子區段。 ### 將追蹤 ID 插入日誌 若要將您日誌陳述式公開給目前的追蹤 ID，您可以將此 ID 插入到映射的診斷內容 (MDC)。使用 `SegmentListener` 界面，會在區段生命週期事件期間從 X-Ray 記錄器呼叫方法。當區段或子區段開始時，合格的追蹤 ID 會透過金鑰 `AWS-XRAY-TRACE-ID` 注入至 MDC。當該區段結束時，該索引鍵即會從 MDC 中移除。這會公開正在使用的記錄程式庫追蹤 ID。當子區段結束時，其父 ID 會注入 MDC 中。 **Example 完整的合格追蹤 ID** 完整的合格 ID 會表示為 `TraceID@EntityID` ``` 1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3 ``` 此功能適用於使用適用於 Java 的 AWS X-Ray 開發套件檢測的 Java 應用程式，並支援下列記錄組態： + SLF4J 前端 API 與 Logback 後端 + SLF4J 前端 API 與 Log4J2 後端 + Log4J2 前端 API 與 Log4J2 後端 請參閱下列標籤，以了解每個前端和每個後端的需求。 ------ #### [ SLF4J Frontend ] 1. 將以下 Maven 相依性新增到您的專案。 ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. 建置 `AWSXRayRecorder` 時包含 `withSegmentListener` 方法。這會新增 `SegmentListener` 類別，將新的追蹤 ID 自動插入 SLF4J MDC。 `SegmentListener` 會採用選擇性字串做為參數來設定日誌陳述式的字首。您可以透過下列方式設定字首： + **無** – 使用預設`AWS-XRAY-TRACE-ID`字首。 + **空白** – 使用空字串 （例如 `""`)。 + **自訂** – 使用字串中定義的自訂字首。 **Example `AWSXRayRecorderBuilder` 陳述式** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Log4J2 front end ] 1. 將以下 Maven 相依性新增到您的專案。 ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. 建置 `AWSXRayRecorder` 時包含 `withSegmentListener` 方法。這會新增 `SegmentListener` 類別，將新的完整合格追蹤 ID 自動注入 SLF4J MDC。 `SegmentListener` 會採用選擇性字串做為參數來設定日誌陳述式的字首。您可以透過下列方式設定字首： + **無** – 使用預設`AWS-XRAY-TRACE-ID`字首。 + **空白** – 使用空字串 （例如 `""`) 並移除字首。 + **自訂** – 使用字串中定義的自訂字首。 **Example `AWSXRayRecorderBuilder` 陳述式** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Logback backend ] 若要將追蹤 ID 插入到日誌事件中，您必須修改記錄器的 `PatternLayout`，這會格式化每個記錄陳述式。 1. 尋找 `patternLayout` 的設定位置。您可透過編寫程式的方式，或透過 XML 組態檔案執行此作業。若要深入了解，請參閱 [Logback 組態](http://logback.qos.ch/manual/configuration.html)。 1. 將 `%X{AWS-XRAY-TRACE-ID}` 插入到 `patternLayout` 的任何位置，可將追蹤 ID 插入未來的記錄陳述式。`%X{}` 表示您正在使用 MDC 提供的索引鍵擷取值。若要深入了解 Logback 中的 PatternLayout，請參閱 [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout)。 ------ #### [ Log4J2 backend ] 1. 尋找 `patternLayout` 的設定位置。您可透過編寫程式的方式，或透過以 XML、JSON、YAML 或屬性格式編寫的組態檔案執行此作業。 若要深入了解如何透過組態檔案設定 Log4J2，請參閱[組態](https://logging.apache.org/log4j/2.x/manual/configuration.html)。 若要深入了解如何透過編寫程式的方式設定 Log4J2，請參閱[透過編寫程式方式的組態](https://logging.apache.org/log4j/2.x/manual/customconfig.html)。 1. 將 `%X{AWS-XRAY-TRACE-ID}` 插入到 `PatternLayout` 的任何位置，可將追蹤 ID 插入未來的記錄陳述式。`%X{}` 表示您正在使用 MDC 提供的索引鍵擷取值。若要深入了解 Log4J2 中的 PatternLayout，請參閱[模式配置](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout)。 ------ **插入追蹤 ID 範例** 以下示範包含追蹤 ID 的修改後 `PatternLayout` 字串。追蹤 ID 會列印在執行緒名稱 (`%t`) 之後、日誌層級 (`%-5p`) 之前。 **Example 插入 ID 的 `PatternLayout`** ``` %d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n ``` AWS X-Ray 會自動列印日誌陳述式中的金鑰和追蹤 ID，以便於剖析。以下顯示使用修改後 `PatternLayout` 的日誌說明。 **Example 插入 ID 的日誌說明** ``` 2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here ``` 記錄訊息本身以 `%m` 模式包裝，在呼叫記錄器時設定。 ## 區段接聽程式 區段接聽程式是攔截生命週期事件的界面，例如 所產生區段的開始和結束`AWSXRayRecorder`。區段接聽程式事件函數的實作可能是在透過 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) 建立時，將相同的註釋新增至所有子區段、使用 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) 將每個區段傳送到精靈後記錄訊息，或者透過 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-)記錄由 SQL 攔截器傳送的查詢，以驗證子區段是否代表 SQL 查詢，如果是的話，則會新增額外的中繼資料。 若要查看`SegmentListener`函數的完整清單，請造訪[AWS X-Ray 適用於 Java 的 Recorder SDK API](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html) 的文件。 下列範例顯示如何在建立 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) 時將一致的註釋加入所有子區段，以及透過 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) 在每個區段結尾列印記錄訊息。 **Example MySegmentListener.java** ``` import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } } ``` 在建立 `AWSXRayRecorder` 時參考此自訂區段接聽程式。 **Example AWSXRayRecorderBuilder statement** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener()); ``` ## 環境變數 您可以使用環境變數來設定適用於 Java 的 X-Ray 開發套件。軟體開發套件支援以下變數。 + `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。 **有效值** + `RUNTIME_ERROR` – 擲回執行時間例外狀況。 + `LOG_ERROR` – 記錄錯誤並繼續 （預設）。 + `IGNORE_ERROR` – 忽略錯誤並繼續。 當您嘗試在未開啟請求時執行的啟動程式碼中使用經檢測的用戶端，或在產生新執行緒的程式碼中，可能會發生與缺少區段或子區段相關的錯誤。 + `AWS_XRAY_DAEMON_ADDRESS` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會使用 `127.0.0.1:2000` 進行追蹤資料 (UDP) 和取樣 (TCP)。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。 **格式** + **相同連接埠** – `address:port` + **不同的連接埠** – `tcp:address:port udp:address:port` + `AWS_LOG_GROUP` – 將日誌群組的名稱設定為與您的應用程式相關聯的日誌群組。如果您的日誌群組使用與您應用程式相同的 AWS 帳戶和區域，X-Ray 會自動使用此指定的日誌群組搜尋應用程式的區段資料。如需日誌群組的詳細資訊，請參閱[使用日誌群組和串流](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)。 + `AWS_XRAY_TRACING_NAME` – 設定 SDK 用於區段的服務名稱。覆寫您在 servlet 篩選條件的[區段命名策略](xray-sdk-java-filters.md#xray-sdk-java-filters-naming)中設定的服務名稱。 環境變數會覆寫程式碼中所設的同等[系統屬性](#xray-sdk-java-configuration-sysprops)和值。 ## 系統屬性 您可以將系統屬性做為[環境變數](#xray-sdk-java-configuration-envvars)的 JVM 專用替代方案。開發套件支援以下屬性： + `com.amazonaws.xray.strategy.tracingName` – 等同於 `AWS_XRAY_TRACING_NAME`。 + `com.amazonaws.xray.emitters.daemonAddress` – 等同於 `AWS_XRAY_DAEMON_ADDRESS`。 + `com.amazonaws.xray.strategy.contextMissingStrategy` – 等同於 `AWS_XRAY_CONTEXT_MISSING`。 如果同時設定了系統屬性和同等環境變數，則會使用環境變數的值。兩種方法都會覆寫程式碼中所設的值。 # 使用適用於 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)。 您可以使用 X-Ray 開發套件來追蹤應用程式在 Amazon EC2 或 Amazon ECS 中的 EC2 執行個體上提供的傳入 HTTP 請求。 AWS Elastic Beanstalk 使用 `Filter` 檢測傳入的 HTTP 請求。當您將 X-Ray servlet 篩選條件新增至應用程式時，適用於 Java 的 X-Ray 開發套件會為每個取樣請求建立區段。此區段包括時間、方法，以及 HTTP 請求的處置方式。其他檢測會在此區段上建立子區段。 **注意** 對於 AWS Lambda 函數，Lambda 會為每個取樣請求建立區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。 每個區段都有一個名稱，可在服務映射中識別您的應用程式。區段可以靜態命名，或者您可以設定 SDK 根據傳入請求中的主機標頭動態命名。動態命名可讓您根據請求中的網域名稱來分組追蹤，並在名稱不符合預期模式時套用預設名稱 （例如，如果主機標頭是偽造的）。 **轉送的請求** 如果負載平衡器或其他中介裝置轉送請求到您的應用程式，X-Ray 會從請求中的 `X-Forwarded-For`標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得用戶端 IP。為轉送請求記錄的用戶端 IP 可能是偽造的，因此不應受信任。 轉送請求時，開發套件會在區段中設定額外的欄位來表示這一點。如果區段包含`x_forwarded_for`設為 的欄位`true`，用戶端 IP 會從 HTTP 請求中的 `X-Forwarded-For`標頭取得。 訊息處理常式會使用 `http` 區塊為每個傳入的請求建立區段，其中包含以下資訊： + **HTTP 方法** – GET、POST、PUT、DELETE 等。 + **用戶端地址** – 傳送請求之用戶端的 IP 地址。 + **回應碼** – 已完成請求的 HTTP 回應碼。 + **時間** – 開始時間 （收到請求的時間） 和結束時間 （傳送回應的時間）。 + **使用者代理程式** — 來自請求`user-agent`的 。 + **內容長度** — `content-length`來自回應的 。 **Topics** + [將追蹤篩選條件新增至應用程式 (Tomcat)](#xray-sdk-java-filters-tomcat) + [將追蹤篩選條件新增至應用程式 (Spring)](#xray-sdk-java-filters-spring) + [設定區段命名策略](#xray-sdk-java-filters-naming) ## 將追蹤篩選條件新增至應用程式 (Tomcat) 若是 Tomcat，請將 `` 新增至您專案的 `web.xml` 檔案。使用 `fixedName` 參數，指定要套用至針對傳入請求建立之區段的[服務名稱](#xray-sdk-java-filters-naming)。 **Example WEB-INF/web.xml - Tomcat** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter fixedName MyApp AWSXRayServletFilter * ``` ## 將追蹤篩選條件新增至應用程式 (Spring) 若是 Spring，請將 `Filter` 新增至您的 `WebConfig` 類別。以字串形式將區段名稱傳遞給 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 建構函數。 **Example src/main/java/myapp/WebConfig.java - Spring** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## 設定區段命名策略 AWS X-Ray 使用*服務名稱*來識別您的應用程式，並將其與您的應用程式使用的其他應用程式、資料庫、外部 APIs AWS 和資源區分開來。當 X-Ray SDK 為傳入請求產生區段時，它會在區段的名稱欄位中記錄應用程式的服務[名稱](xray-api-segmentdocuments.md#api-segmentdocuments-fields)。 X-Ray SDK 可以在 HTTP 請求標頭中的主機名稱之後命名區段。不過，此標頭可以偽造，這可能會導致服務映射中出現非預期的節點。若要防止 SDK 因具有偽造主機標頭的請求而不正確地命名區段，您必須指定傳入請求的預設名稱。 如果您的應用程式為多個網域提供請求，您可以將 SDK 設定為使用動態命名策略，以在區段名稱中反映這一點。動態命名策略可讓軟體開發套件針對符合預期模式的請求使用主機名稱，並將預設名稱套用至不符合的請求。 例如，您可能有一個應用程式向三個子網域提供請求：`www.example.com`、 `api.example.com`和 `static.example.com`。您可以使用動態命名策略搭配 模式`*.example.com`，以不同名稱識別每個子網域的區段，在服務映射上產生三個服務節點。如果您的應用程式收到主機名稱與模式不相符的請求，您會在服務映射上看到具有您指定之備用名稱的第四個節點。 若要為所有請求區段使用相同的名稱，請如[上一節](#xray-sdk-java-filters-tomcat)所述，在初始化 servlet 篩選條件時指定您應用程式的名稱。這與透過呼叫`SegmentNamingStrategy.fixed()`並傳遞給建構函數來建立固定的 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html) [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 具有相同的效果。 **注意** 您可以使用 `AWS_XRAY_TRACING_NAME` [環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)來覆寫您在程式碼中定義的預設服務名稱。 動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要在 Tomcat 中動態命名區段，請分別使用 `dynamicNamingRecognizedHosts` 和 `dynamicNamingFallbackName` 來定義模式和預設名稱。 **Example WEB-INF/web.xml - 使用動態命名的 Servlet 篩選條件** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter dynamicNamingRecognizedHosts *.example.com dynamicNamingFallbackName MyApp AWSXRayServletFilter * ``` 對於 Spring，透過呼叫 建立動態 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)`SegmentNamingStrategy.dynamic()`，並將其傳遞給`AWSXRayServletFilter`建構函數。 **Example src/main/java/myapp/WebConfig.java - 使用動態命名的 Servlet 篩選條件** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com")); } } ``` # 使用適用於 Java 的 X-Ray AWS 開發套件追蹤 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)。 當您的應用程式呼叫 AWS 服務 來存放資料、寫入佇列或傳送通知時，適用於 Java 的 X-Ray 開發套件會在[子區段](xray-sdk-java-subsegments.md)中追蹤下游的呼叫。您在這些服務中存取的追蹤 AWS 服務 和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。 當您在建置中包含 `aws-sdk`和 `aws-sdk-instrumentor`[子模組時，適用於 Java 的](xray-sdk-java.md#xray-sdk-java-submodules) X-Ray 開發套件會自動檢測所有 AWS 開發套件用戶端。如果您未包含 Instrumentor 子模組，您可以選擇檢測某些特定用戶端，而排除其他用戶端。 若要檢測個別用戶端，請從您的建置中移除 `aws-sdk-instrumentor` 子模組，並使用 服務的用戶端建置器，在 AWS SDK 用戶端`TracingHandler`上新增 `XRayClient`做為 。 例如，若要檢測 `AmazonDynamoDB` 用戶端，請將追蹤處理常式傳遞至 `AmazonDynamoDBClientBuilder`。 **Example MyModel.java - DynamoDB 用戶端** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); ... public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); ... ``` 對於所有 服務，您可以在 X-Ray 主控台中查看名為 的 API 名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務映射中提供更精細的服務。 例如，當您使用經檢測的 DynamoDB 用戶端進行呼叫時，軟體開發套件會將資料表名稱新增至以資料表為目標的呼叫區段。在 主控台中，每個資料表會在服務映射中顯示為個別節點，並針對非資料表目標的呼叫使用一般 DynamoDB 節點。 **Example 呼叫 DynamoDB 以儲存項目的子區段** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` 您存取具名資源時，對以下服務的呼叫會在服務地圖中建立額外節點。未針對特定資源的呼叫，則會建立服務的一般節點。 + **Amazon DynamoDB** – 資料表名稱 + **Amazon Simple Storage Service** – 儲存貯體和金鑰名稱 + **Amazon Simple Queue Service** – 佇列名稱 若要 AWS 服務 使用 適用於 Java 的 AWS SDK 2.2 和更新版本檢測對 的下游呼叫，您可以從建置組態中省略 `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor`模組。這時改成包含 `aws-xray-recorder-sdk-aws-sdk-v2 module`，然後使用 `TracingInterceptor` 為其進行設定，檢測個別的用戶端。 **Example 適用於 Java 的 AWS SDK 2.2 及更新版本 - 追蹤攔截器** ``` import com.amazonaws.xray.interceptors.TracingInterceptor; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration import software.amazon.awssdk.services.dynamodb.DynamoDbClient; //... public class MyModel { private DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_WEST_2) .overrideConfiguration(ClientOverrideConfiguration.builder() .addExecutionInterceptor(new TracingInterceptor()) .build() ) .build(); //... ``` # 使用適用於 Java 的 X-Ray 開發套件追蹤對下游 HTTP Web 服務的呼叫 **注意** 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)。 當您的應用程式呼叫微服務或公有 HTTP APIs，您可以使用適用於 Java 的 X-Ray 開發套件 版本`HttpClient`來檢測這些呼叫，並將 API 做為下游服務新增至服務圖表。 適用於 Java 的 X-Ray 開發套件包含 `DefaultHttpClient`和 `HttpClientBuilder`類別，可用於取代 Apache HttpComponents 對等項目，以檢測傳出的 HTTP 呼叫。 + `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient` + `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder` 這些程式庫位於 [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md) 子模組中。 您可以使用等同於檢測所有用戶端的 X-Ray 取代現有的匯入陳述式，或在初始化用戶端以檢測特定用戶端時使用完整名稱。 **Example HttpClientBuilder** ``` import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.util.EntityUtils; import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); ... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` 當您檢測對下游 Web api 的呼叫時，適用於 Java 的 X-Ray 開發套件會記錄子區段，其中包含 HTTP 請求和回應的相關資訊。X-Ray 使用子區段來產生遠端 API 的推斷區段。 **Example 下游 HTTP 呼叫的子區段** ``` { "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } } ``` **Example 下游 HTTP 呼叫的推斷區段** ``` { "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-62be1272-1b71c4274f39f122afa64eab", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true } ``` # 使用適用於 Java 的 X-Ray 開發套件追蹤 SQL 查詢 **注意** 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)。 ## SQL 攔截器 將適用於 Java JDBC 的 X-Ray 開發套件攔截器新增至資料來源組態，以檢測 SQL 資料庫查詢。 + **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor` + **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor` 這些攔截器分別位於 [`aws-xray-recorder-sql-postgres` 和 `aws-xray-recorder-sql-mysql` 子模組](xray-sdk-java.md)中。他們會實作 `org.apache.tomcat.jdbc.pool.JdbcInterceptor`，並且與 Tomcat 連線集區相容。 **注意** 基於安全性目的，SQL 攔截器不會在子區段內記錄 SQL 查詢本身。 針對 Spring，請在屬性檔案中新增攔截器，然後使用 Spring Boot 的 `DataSourceBuilder` 建置資料來源。 **Example `src/main/java/resources/application.properties` - PostgreSQL JDBC 攔截器** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Example `src/main/java/myapp/WebConfig.java` - 資料來源** ``` import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.jpa.repository.config.EnableJpaRepositories; import javax.servlet.Filter; import javax.sql.DataSource; import java.net.URL; @Configuration @EnableAutoConfiguration @EnableJpaRepositories("myapp") public class RdsWebConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); } ... } ``` 對於 Tomcat，請在 JDBC 資料來源`setJdbcInterceptors`上呼叫 ，並參考適用於 Java 的 X-Ray 開發套件類別。 **Example `src/main/myapp/model.java` - 資料來源** ``` import org.apache.tomcat.jdbc.pool.DataSource; ... DataSource source = new DataSource(); source.setUrl(url); source.setUsername(user); source.setPassword(password); source.setDriverClassName("com.mysql.jdbc.Driver"); source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;"); ``` Tomcat JDBC 資料來源程式庫包含在適用於 Java 的 X-Ray 開發套件中，但您可以將其宣告為提供相依性，以記錄您使用它。 **Example `pom.xml` - JDBC 資料來源** ``` org.apache.tomcat tomcat-jdbc 8.0.36 provided ``` ## 原生 SQL 追蹤裝飾項目 + 將 [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)新增至您的相依性。 + 裝飾資料庫資料來源、連線或陳述式。 ``` dataSource = TracingDataSource.decorate(dataSource) connection = TracingConnection.decorate(connection) statement = TracingStatement.decorateStatement(statement) preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql) callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql) ``` # 使用適用於 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)。 子區段會延伸追蹤的[區段](xray-concepts.md#xray-concepts-segments)，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，X-Ray 開發套件都會記錄子區段中產生的資訊。您可以建立其他子區段來將其他子區段分組、測量程式碼區段的效能，或記錄註釋和中繼資料。 若要管理子區段，請使用 `beginSubsegment` 和 `endSubsegment` 方法。 **Example GameModel.java - 自訂子區段** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` 在此範例中，子區段中的程式碼會使用工作階段模型上的 方法從 DynamoDB 載入遊戲的工作階段，並使用 適用於 Java 的 AWS SDK的 DynamoDB 映射器來儲存遊戲。在 主控台的追蹤檢視中，將此程式碼包裝在子區段中會呼叫`Save Game`子區段的 DynamoDB 子系。 ![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) 如果子區段中的程式碼擲回已檢查的例外狀況，請將其包裝在 `try` 區塊中，並在 `finally` 區塊中呼叫 `AWSXRay.endSubsegment()`，以確保子區段一律關閉。如果子區段未關閉，則無法完成父區段，也不會傳送至 X-Ray。 對於未擲回核取例外狀況的程式碼，您可以將程式碼`AWSXRay.CreateSubsegment`做為 Lambda 函數傳遞至 。 **Example 子區段 Lambda 函數** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code }); ``` 當您在區段或其他子區段中建立子區段時，適用於 Java 的 X-Ray 開發套件會為其產生 ID，並記錄開始時間和結束時間。 **Example 使用中繼資料的子區段** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` 對於非同步和多執行緒程式設計，您必須手動將子區段傳遞至 `endSubsegment()`方法，以確保其正確關閉，因為 X-Ray 內容可能會在非同步執行期間修改。如果非同步子區段在其父區段關閉後關閉，此方法會自動將整個區段串流到 X-Ray 協助程式。 **Example 非同步子區段** ``` @GetMapping("/api") public ResponseEntity api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build(); } ``` # 使用適用於 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)。 您可以使用註釋和中繼資料記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray 開發套件建立的區段，或新增至您建立的自訂子區段。 **註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。 **中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。 除了註釋和中繼資料，您也可以在區段上[記錄使用者 ID 字串](#xray-sdk-java-segment-userid)。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。 **Topics** + [使用適用於 Java 的 X-Ray 開發套件記錄註釋](#xray-sdk-java-segment-annotations) + [使用適用於 Java 的 X-Ray 開發套件記錄中繼資料](#xray-sdk-java-segment-metadata) + [使用適用於 Java IDs](#xray-sdk-java-segment-userid) ## 使用適用於 Java 的 X-Ray 開發套件記錄註釋 針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。 **註釋要求** + **金鑰** – X-Ray 註釋的金鑰最多可有 500 個英數字元。您不能使用點或句點以外的空格或符號 ( 。 ) + **值** – X-Ray 註釋的值最多可有 1，000 個 Unicode 字元。 + **註釋**數量 – 每個追蹤最多可以使用 50 個註釋。 **記錄標註** 1. 從 `AWSXRay` 取得目前區段或子區段的參考。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 或 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. 使用字串索引鍵、布林值、數字或字串值，呼叫 `putAnnotation`。 ``` document.putAnnotation("mykey", "my value"); ``` 下列範例顯示如何使用包含點的`putAnnotation`字串索引鍵和布林值、數字或字串值來呼叫 。 ``` document.putAnnotation("testkey.test", "my value"); ``` 軟體開發套件會將標註以鍵/值對記錄在區段文件中的 `annotations` 物件內。若使用相同鍵呼叫 `putAnnotation` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。 若要尋找具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 註釋和中繼資料** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## 使用適用於 Java 的 X-Ray 開發套件記錄中繼資料 針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。中繼資料值可以是字串、數字、布林值，或可序列化為 JSON 物件或陣列的任何物件。 **記錄中繼資料** 1. 從 `AWSXRay` 取得目前區段或子區段的參考。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 或 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. 使用字串命名空間、字串索引鍵、布林值、數字、字串或物件值，呼叫 `putMetadata`。 ``` document.putMetadata("my namespace", "my key", "my value"); ``` 或 只使用鍵和值呼叫 `putMetadata`。 ``` document.putMetadata("my key", "my value"); ``` 若您沒有指定命名空間，軟體開發套件會使用 `default`。若使用相同鍵呼叫 `putMetadata` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 註釋和中繼資料** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## 使用適用於 Java IDs 記錄請求區段上的使用者 ID 以識別傳送請求的使用者。 **記錄使用者 ID** 1. 從 `AWSXRay` 取得目前區段的參考。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 1. 使用傳送請求之使用者的字串 ID 呼叫 `setUser`。 ``` document.setUser("U12345"); ``` 您可以在控制器中呼叫 `setUser`，以在應用程式開始處理請求時馬上記錄使用者 ID。如果您只要使用區段來設定使用者 ID，可以將呼叫鏈結為單行。 **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) – 使用者 ID** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` 若要尋找使用者 ID 的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `user`關鍵字。 ## 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`日誌群組。尋找符合主機指標的日誌資料流，並確認日誌訊息。 # 在多執行緒應用程式之間傳遞區段內容 **注意** 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)。 當您在應用程式中建立新執行緒時，`AWSXRayRecorder` 不會維持目前區段或子區段[實體](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html)的參考。若您在新執行緒中使用受檢測的用戶端，軟體開發套件會嘗試寫入不存在的區段，且會導致 [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)。 若要避免在開發期間拋出異常，您可以使用 [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html) 設定記錄器，告知其改而記錄錯誤。您可以使用 [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy)) 在程式碼中設定策略，或是使用[環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)或[系統屬性](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)來設定相等選項。 其中一種處理錯誤的方法是透過在啟動執行緒時呼叫 [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) 來使用新區段，以及在關閉時呼叫 [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--)。若您要檢測並非針對回應 HTTP 請求而執行的程式碼，這種方法可以正常運作，就像在應用程式啟動時執行的程式碼。 若您使用多個執行緒來處理傳入請求，您可以將目前區段或子區段傳遞至新執行緒，並將它提供給全域記錄器。這可確保在記錄該請求的其餘資訊時，於新執行緒中記錄的資訊會與相同區段建立關聯。區段在新執行緒中可用後，您可以使用 `segment.run(() -> { ... })`方法執行可存取該區段內容的任何可執行項目。 如需範例，請參閱[在工作者執行緒中使用受檢測用戶端](scorekeep-workerthreads.md)。 ## 搭配非同步程式設計使用 X-Ray 適用於 Java 的 X-Ray 開發套件可用於具有 [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) 的非同步 Java 程式。SegmentContextExecutor 實作執行器界面，這表示它可以傳遞至 [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) 的所有非同步操作。這可確保任何非同步操作都會在其內容中使用正確的區段執行。 **Example App.java 範例：將 SegmentContextExecutor 傳遞至 CompletableFuture** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.create(); AWSXRay.beginSegment(); // ... client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2); }, SegmentContextExecutors.newSegmentContextExecutor()); ``` # 搭配 Spring 和適用於 Java 的 X-Ray 開發套件的 AOP **注意** 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)。 本主題說明如何使用 X-Ray SDK 和 Spring Framework 來檢測您的應用程式，而無需變更其核心邏輯。這表示現在有一種非侵入性的方式來檢測從遠端執行的應用程式 AWS。 **啟用 Spring 中的 AOP** 1. [設定 Spring](#xray-sdk-java-aop-spring-configuration) 1. [將追蹤篩選條件新增至您的應用程式](#xray-sdk-java-aop-filters-spring) 1. [對您的程式碼做註釋或實作界面](#xray-sdk-java-aop-annotate-or-implement) 1. [啟用應用程式中的 X-Ray](#xray-sdk-java-aop-activate-xray) ## 設定 Spring 您可以使用 Maven 或 Gradle 將 Spring 設定為使用 AOP 檢測您的應用程式。 如果您使用 Maven 來建置應用程式，請在 `pom.xml` 檔案中，新增以下相依性。 ``` com.amazonaws aws-xray-recorder-sdk-spring 2.11.0 ``` 若是 Gradle，請在 `build.gradle` 檔案中，新增以下依存性。 ``` compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0' ``` ## 設定 Spring Boot 除了上一節所述的 Spring 相依性之外，如果您使用的是 Spring Boot，如果尚未在 classpath 上新增下列相依性。 Maven： ``` org.springframework.boot spring-boot-starter-aop 2.5.2 ``` Gradle： ``` compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2' ``` ## 將追蹤篩選條件新增至您的應用程式 將 `Filter`新增至您的 `WebConfig` 類別。以字串形式將區段名稱傳遞給 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 建構函數。如需追蹤篩選條件和檢測傳入請求的詳細資訊，請參閱[使用適用於 Java 的 X-Ray 開發套件追蹤傳入請求](xray-sdk-java-filters.md)。 **Example src/main/java/myapp/WebConfig.java - Spring** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## 雅加達支援 Spring 6 使用 [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) 而非 Javax 做為其 Enterprise Edition。為了支援這個新的命名空間，X-Ray 建立了一組平行的類別，這些類別存在於自己的雅加達命名空間中。 對於篩選條件類別，請將 取代`javax`為 `jakarta`。設定區段命名策略時，請在命名策略類別名稱`jakarta`之前新增 ，如下列範例所示： ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import jakarta.servlet.Filter; import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter; import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy; @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep")); } } ``` ## 對您的程式碼做註釋或實作界面 您的類別必須以註釋標註`@XRayEnabled`，或實作`XRayTraced`界面。這會通知 AOP 系統，針對 X-Ray 檢測包裝受影響的類別函數。 ## 在應用程式中啟用 X-Ray 若要在您的應用程式中啟用 X-Ray 追蹤，您的程式碼必須透過覆寫下列方法`BaseAbstractXRayInterceptor`來擴展抽象類別。 + `generateMetadata`- 此函數允許自訂連接至目前函數追蹤的中繼資料。根據預設，執行函數的類別名稱會記錄到中繼資料中。如果您需要其他資訊，可以新增更多資料。 + `xrayEnabledClasses`- 此函數為空，應保持為空。可做為 pointcut 的主機，指示攔截程式有哪些包裝方法。指定哪些類別要使用 `@XRayEnabled` 做註釋以便追蹤，藉此定義 pointcut。以下 pointcut 陳述式會通知攔截程式包裝所有含 `@XRayEnabled` 註釋的控制器 Bean。 ``` @Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”) ``` 如果您的專案使用 Spring Data JPA，請考慮從 延伸，`AbstractXRayInterceptor`而非 `BaseAbstractXRayInterceptor`。 ## 範例 下列程式碼延伸抽象類別 `BaseAbstractXRayInterceptor`。 ``` @Aspect @Component public class XRayInspector extends BaseAbstractXRayInterceptor { @Override protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} } ``` 下列程式碼為將由 X-Ray 檢測的類別。 ``` @Service @XRayEnabled public class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List getMyEntities(){ try(Stream entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } } } ``` 如果您已正確設定應用程式，則應該會看到應用程式的完整呼叫堆疊 (從控制器到服務呼叫)，如以下主控台的螢幕擷取畫面所示。 ![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/aop-spring-console.png)