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

# 使用適用於 Java 的 X-Ray 開發套件產生自訂子區段
<a name="xray-sdk-java-subsegments"></a>

**注意**  
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();
}
```