本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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\_XRAY\_TRACING\_NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | String | LOG\_ERROR、IGNORE\_ERROR | 當代理程式嘗試使用 X-Ray 區段內容但不存在時所採取的動作。 | AWS\_XRAY\_CONTEXT\_MISSING | com.amazonaws.xray.strategy.contextMissingStrategy | LOG\_ERROR |
| daemonAddress | String | 格式化 IP 地址和連接埠，或 TCP 和 UDP 地址清單 | 代理程式用來與 X-Ray 協助程式通訊的地址。 | AWS\_XRAY\_DAEMON\_ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1：2000 |
| tracingEnabled | Boolean | True、False | 啟用 X-Ray 代理程式的檢測。 | AWS\_XRAY\_TRACING\_ENABLED | 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)。