使用適用於 Java 的 X-Ray 開發套件產生自訂子區段 - AWS X-Ray

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用適用於 Java 的 X-Ray 開發套件產生自訂子區段

注意

X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 X-Ray SDK 和協助程式支援時間表。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱從 X-Ray 檢測遷移至 OpenTelemetry 檢測。

子區段會延伸追蹤的區段，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，X-Ray 開發套件都會記錄子區段中產生的資訊。您可以建立其他子區段來將其他子區段分組、測量程式碼區段的效能，或記錄註釋和中繼資料。

若要管理子區段，請使用 beginSubsegment 和 endSubsegment 方法。

範例 GameModel.java - 自訂子區段
import com.amazonaws.xray.AWSXRay;
...
  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 載入遊戲的工作階段，並使用 AWS SDK for Java的 DynamoDB 映射器來儲存遊戲。在子區段中包裝此程式碼會在 主控台的追蹤檢視中呼叫Save Game子區段的 DynamoDB 子系。

Timeline showing Scorekeep and DynamoDB operations with durations and status checks.

如果子區段中的程式碼擲回已檢查的例外狀況，請將其包裝在 try 區塊中，並在 finally 區塊中呼叫 AWSXRay.endSubsegment()，以確保子區段一律關閉。如果子區段未關閉，則無法完成父區段，也不會傳送至 X-Ray。

對於未擲回核取例外狀況的程式碼，您可以將程式碼AWSXRay.CreateSubsegment做為 Lambda 函數傳遞至 。

範例子區段 Lambda 函數
import com.amazonaws.xray.AWSXRay;

AWSXRay.createSubsegment("getMovies", (subsegment) -> {
    // function code
});

當您在區段或其他子區段中建立子區段時，適用於 Java 的 X-Ray 開發套件會為其產生 ID，並記錄開始時間和結束時間。

範例使用中繼資料的子區段
"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 協助程式。

範例非同步子區段

@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();
}