기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Java용 X-Ray SDK를 사용하여 사용자 지정 하위 세그먼트 생성하기
<a name="xray-sdk-java-subsegments"></a>

**참고**  
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [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 SDK는 하위 세그먼트 안에 생성된 정보를 기록합니다. 추가 하위 세그먼트를 생성하여 다른 하위 세그먼트를 그룹화하거나, 코드 섹션의 성능을 평가하거나, 주석 및 메타데이터를 기록할 수 있습니다.

하위 세그먼트를 관리하려면 `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에서 게임의 세션을 로드하고 AWS SDK for Java의 DynamoDB 매퍼를 사용하여 게임을 저장합니다. 하위 세그먼트에서 이 코드를 래핑하면 콘솔의 추적 보기에서 `Save Game` 하위 세그먼트의 DynamoDB 하위가 호출됩니다.

![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png)


하위 세그먼트 내 코드가 확인된 예외를 내보낼 경우 하위 세그먼트가 항상 닫히도록 코드를 `try` 블록에 래핑하고 `finally` 블록에서 `AWSXRay.endSubsegment()`를 호출합니다. 하위 세그먼트가 닫히지 않는 경우 상위 세그먼트가 완료될 수 없으며 X-Ray로 전송되지 않습니다.

확인된 예외를 내보내지 않는 코드의 경우 코드를 Lambda 함수로 `AWSXRay.CreateSubsegment`에 전달할 수 있습니다.

**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 SDK가 해당 하위 세그먼트에 대해 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"
    }
  },
```

비동기 및 다중 스레드 프로그래밍의 경우 비동기 실행 중에 X-Ray 컨텍스트가 수정될 수 있으므로 하위 세그먼트를 `endSubsegment()` 메서드에 수동으로 전달하여 올바르게 닫히도록 해야 합니다. 상위 세그먼트가 닫힌 후 비동기 하위 세그먼트가 닫히면, 이 메서드는 전체 세그먼트를 자동으로 X-Ray 대몬(daemon)으로 스트리밍합니다.

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