本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定適用於 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`。 如果同時設定了系統屬性和同等環境變數，則會使用環境變數的值。兩種方法都會覆寫程式碼中所設的值。