AWS X-Ray 適用於 Java 的自動檢測代理

Java 的 AWS X-Ray 自動檢測代理是一種跟踪解決方案，用最少的開發工作來測量您的 Java Web 應用程序。代理程式可追蹤以伺服器為基礎的應用程式，以及使用支援的架構和程式庫所發出的代理程式下游要求。這包括下游 Apache HTTP 請求、 AWS SDK請求和使用JDBC驅動程序進行的SQL查詢。代理程式會跨執行緒傳播 X-Ray 環境，包括所有作用中區段和子區段。Java 代理程式仍可使用 X-Ray 的所SDK有配置和多功能性。選擇了合適的預設值，以確保代理程式以最小的努力工作。

X-Ray 代理程式解決方案最適合以伺服器為基礎的要求-回應 Java Web 應用程式伺服器。如果您的應用程式使用非同步架構，或未正確建模為要求-回應服務，您可能需要考慮改用手動檢測。SDK

X-Ray 代理是使用分佈式系統理解工具包或 D 構建的iSCo。D iSCo 是用於構建可在分佈式系統中使用的 Java 代理的開源框架。雖然不需要了解 D 即可使用 X-Ray 劑，但您可以通過訪問該項目的主頁iSCo 來了解有關該項目的更多信息 GitHub。X-Ray 劑也是完全開源的。若要檢視原始程式碼、做出貢獻或提出有關代理程式的問題，請造訪其存放庫 (位於) GitHub。

範例應用程式

eb-java-scorekeep樣品應用程序適用於與 X-Ray 劑一起進行檢測。此分支不包含 servlet 篩選器或記錄器組態，因為這些功能是由代理程式完成的。若要在本機執行應用程式或使用 AWS 資源，請依照範例應用程式的 Readme 檔案中的步驟執行。示例應用程序的教程中有關使用示例應用程序生成 X-Ray 跟踪的說明。

開始使用

若要在您自己的應用程式中開始使用 X-Ray 自動檢測 Java 代理程式，請依照下列步驟執行。

在您的環境中執行 X-Ray 精靈。如需詳細資訊，請參閱 AWS X-Ray 守護進。

下載代理程式的最新發行版本。解壓縮存檔並記下其在您的檔案系統中的位置。其內容應如下所示。

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

修改應用程式的JVM引數以包含下列項目，以啟用代理程式。確保引-javaagent數放在引-jar數之前（如果適用）。修改JVM引數的程序會根據您用來啟動 Java 伺服器的工具和架構而有所不同。如需具體指引，請參閱伺服器架構的文件。
```
-javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
```
若要指定應用程式名稱在 X-Ray 主控台上的顯示方式，請設定AWS_XRAY_TRACING_NAME環境變數或com.amazonaws.xray.strategy.tracingName系統性質。如果未提供名稱，則會使用預設名稱。
重新啟動伺服器或容器。現在會追蹤傳入要求及其下游呼叫。如果您沒有看到預期的結果，請參閱故障診斷。

組態

X-Ray 代理程式是由使用者提供的外部JSON檔案所設定。依預設，此檔案位於名為的使用者類別路徑 (例如，在其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 
}

組態規格

下表說明每個屬性的有效值。屬性名稱區分大小寫，但其索引鍵則不區分大小寫。對於可以被環境變數和系統性質覆寫的性質，優先順序永遠是環境變數，然後是系統屬性，然後是組態檔案。若要取得有關可取代之性質的資訊，請參閱〈〉環境變數。所有欄位都是選擇性的。

屬性名稱	Type	有效值	描述	環境變數	系統屬性	預設
serviceName	字串	任何字串	檢測服務將顯示在 X-Ray 主控台中的名稱。	AWS_XRAY_TRACING_NAME	通過. 亞馬遜. X. 策略. tracingName	XRayInstrumentedService
contextMissingStrategy	字串	LOG_ERROR, IGNORE_ERROR	代理程式嘗試使用 X-Ray 區段前後關聯但不存在時所採取的動作。	AWS_XRAY_CONTEXT_MISSING	通過. 亞馬遜. X. 策略. contextMissingStrategy	LOG_ERROR
daemonAddress	字串	格式化的 IP 地址和端口，或TCP和地UDP址列表	代理程式用來與 X-Ray 精靈通訊的位址。	AWS_XRAY_DAEMON_ADDRESS	com. 亞馬遜. X 雷. 發射器. daemonAddress	127.0.0. 1:2000
tracingEnabled	Boolean	真假	啟用 X-Ray 代理程式的檢測。	AWS_XRAY_TRACING_ENABLED	由. 亞馬遜. X 射線. tracingEnabled	TRUE
samplingStrategy	字串	CENTRAL, LOCAL, NONE, ALL	代理程式所使用的取樣策略。ALL捕獲所有請求，不NONE捕獲請求。請參閱取樣規則。	N/A	N/A	CENTRAL
traceIdInjection前綴	字串	任何字串	IDs在記錄檔中插入追蹤之前包含提供的前置詞。	N/A	N/A	無（空字符串）
samplingRulesManifest	字串	絕對檔案路徑	自訂取樣規則檔案的路徑，用作本機抽樣策略的取樣規則來源，或中央策略的後援規則。	N/A	N/A	DefaultSamplingRules.json
awsServiceHandler清單	字串	絕對檔案路徑	自訂參數允許清單的路徑，此清單會從 AWS SDK用戶端擷取其他資訊。	N/A	N/A	DefaultOperationParameterWhitelist.json
awsSdkVersion	Integer	1、2	您正在使AWS SDK用的 Java 版本。忽略`awsServiceHandlerManifest`，如果沒有也設置。	N/A	N/A	2
maxStackTrace長度	Integer	非負整數	要記錄在追蹤中的堆疊追蹤的最大行數。	N/A	N/A	50
streamingThreshold	Integer	非負整數	在至少關閉這麼多子區段之後，它們會串流至守護進程， out-of-band 以避免區塊太大。	N/A	N/A	100
traceIdInjection	Boolean	真假	如果還添加了日誌配置中描述的依賴關係和配置，則啟用 X-Ray 跟踪 ID 插入到日誌中。否則，什麼都不做。	N/A	N/A	TRUE
pluginsEnabled	Boolean	真假	啟用可記錄您正在操作 AWS 環境的中繼資料的外掛程式。請參閱插件。	N/A	N/A	TRUE
collectSqlQueries	Boolean	真假	以最佳方式記錄SQL子區段中的SQL查詢字串。	N/A	N/A	FALSE
contextPropagation	Boolean	真假	如果為 true，則自動在執行緒之間傳播 X-Ray 環境否則，使用「本地線程」來存儲上下文，並且需要跨線程進行手動傳播。	N/A	N/A	TRUE

記錄設定

X-Ray 代理程式的記錄層級可以設定方式與 Java 的 X-Ray SDK 相同。日誌如需使用 Java 的 X-Ray SDK 設定記錄的詳細資訊，請參閱。

手動儀器

如果您希望除了代理程式的自動檢測之外執行手動檢測，請將 X-Ray SDK 作為專案的依賴項加入。請注意，追蹤內送要求中提到SDK的自訂 Servlet 篩選器與 X-Ray 代理程式不相容。

注意

在使用代理程式時，您必須使用最新版本的 X-Ray SDK 來執行手動檢測。

如果您正在 Maven 項目中工作，請將以下依賴項添加到pom.xml文件中。


<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

如果您正在使用 Gradle 項目，請將以下依賴項添加到build.gradle文件中。


implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'

在使用代理程式IDs時，除了註釋、中繼資料和使用者之外，您還可以新增自訂子區段，就像使用正常SDK情況一樣。代理程式會自動跨執行緒傳播內容，因此在處理多執行緒應用程式時，不需要傳播內容的因應措施。

故障診斷

由於代理程式提供全自動檢測，因此在您遇到問題時，很難找出問題的根本原因。如果 X-Ray 代理程式無法如預期般運作，請檢閱下列問題和解決方案。X-Ray 劑和SDK使用雅加達公共資源記錄（JCL）。要查看日誌記錄輸出，請確保連接JCL到日誌記錄後端的橋接器位於類路徑上，如以下示例所示：log4j-jcl或。jcl-over-slf4j

問題：我已在應用程式上啟用 Java 代理程式，但在 X-Ray 主控台上看不到任何內容

X-Ray 守護程序是否在同一台機器上運行？

如果沒有，請參閱 X-Ray 守護程序文件以進行設定。

在應用程式記錄檔中，您是否看到「初始化 X-Ray 代理程式記錄器」之類的訊息？

如果您已正確地將代理程式新增至應用程式，則此訊息會在應用程式啟動時以及開始接受要求之前記錄在INFO層級。如果此消息不存在，則表示 Java 代理程序不與您的 Java 進程一起運行。確保您已正確執行所有設置步驟，沒有錯別字。

在您的應用程序日誌中，您是否看到幾條錯誤消息，說「抑制 AWS X-Ray 上下文丟失異常」？

發生這些錯誤的原因是代理程式嘗試檢測下游要 AWS SDK求 (例如要求或SQL查詢)，但代理程式無法自動建立區段。如果您看到許多這些錯誤，代理程式可能不是您使用案例的最佳工具，SDK而且您可能想要考慮使用 X-Ray 進行手動檢測。或者，您也可以啟用 X-Ray SDK 偵錯記錄檔，查看發生內容遺失例外狀況的堆疊追蹤。您可以使用自定義段包裝代碼的這些部分，這應該可以解決這些錯誤。如需使用自訂區段包裝下游要求的範例，請參閱檢測啟動程式碼中的範例程式碼。

問題：我預期的某些區段不會出現在 X-Ray 主控台上

您的應用程序是否使用多線程？

如果您希望建立的某些區段未出現在主控台中，則應用程式中的背景執行緒可能是原因。如果您的應用程式使用「觸發而忘記」的背景執行緒執行工作，例如使用執行緒對 Lambda 函數進行一次性呼叫 AWS SDK，或定期輪詢某個HTTP端點，這可能會在代理程式跨執行緒傳播內容時造成混淆。若要驗證這是您的問題，請啟用 X-Ray SDK 偵錯記錄檔並檢查訊息，例如：不發出名為 < NAME > 的區段，因為它是父項進行中的子區段。為了解決這個問題，您可以嘗試在服務器返回之前加入後台線程，以確保記錄其中完成的所有工作。或者，您可以將代理程式的contextPropagation組態設定為停false用背景執行緒中的內容傳播。如果這樣做，則必須手動檢測具有自定義段的線程，或者忽略它們生成的上下文缺少異常。

您是否設定了抽樣規則？

如果 X-Ray 主控台上出現看似隨機或未預期的區段，或是您預期位於主機上的區段不是，您可能會遇到取樣問題。X-Ray 代理程式會使用 X-Ray 主控台中的規則，將集中取樣套用至其建立的所有區段。預設規則為每秒 1 個區段，再加上之後 5% 的區段進行取樣。這表示使用代理程式快速建立的區段可能不會進行取樣。若要解決此問題，您應該在 X-Ray 主控台上建立自訂取樣規則，以適當地取樣所需的區段。如需詳細資訊，請參閱取樣。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

爪哇SDK的 X-Ray

組態