기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS X-Ray Java용 SDK
**참고**
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)을 참조하세요.
Java용 X-Ray SDK는 트레이스 데이터를 생성하고 X-Ray 대몬(daemon)에 보내기 위한 클래스 및 메서드를 제공하는 Java 웹 애플리케이션용 라이브러리 집합입니다. 추적 데이터에는 애플리케이션에서 제공하는 수신 HTTP 요청과 애플리케이션이 AWS SDK, HTTP 클라이언트 또는 SQL 데이터베이스 커넥터를 사용하여 다운스트림 서비스에 수행하는 호출에 대한 정보가 포함됩니다. 또한 수동으로 세그먼트를 생성하고 디버그 정보를 주석 및 메타데이터에 추가할 수도 있습니다.
Java용 X-Ray SDK는 오픈 소스 프로젝트입니다. 프로젝트를 따르고 GitHub([github.com/aws/aws-xray-sdk-java](https://github.com/aws/aws-xray-sdk-java))에서 문제 및 풀 요청을 제출할 수 있습니다.
[`AWSXRayServletFilter`를 서블릿 필터로 츄가](xray-sdk-java-filters.md)하여 수신 요청 트레이스를 시작합니다. 서블릿 필터가 [세그먼트](xray-concepts.md#xray-concepts-segments)를 생성합니다. 세그먼트가 열려 있는 동안에는 SDK 클라이언트의 메서드를 이용해 정보를 세그먼트에 추가하고 하위 세그먼트를 만들어 다운스트림 호출을 트레이스할 수 있습니다. 또한 SDK는 세그먼트가 열려 있는 동안 애플리케이션에서 발생하는 예외를 자동으로 기록합니다.
릴리스 1.3부터는 [Spring에서 관점 지향 프로그래밍(AOP)](xray-sdk-java-aop-spring.md)을 사용하여 애플리케이션을 계측할 수 있습니다. 즉, 애플리케이션을 실행하는 동안 애플리케이션의 런타임에 코드를 추가하지 AWS않고도 애플리케이션을 계측할 수 있습니다.
그런 다음 Java용 X-Ray SDK를 사용하여 빌드 구성에 SDK Instrumentor 하위 모듈을 포함하여 AWS SDK for Java 클라이언트를 계측합니다. [종속성 관리](#xray-sdk-java-dependencies) 계측된 클라이언트를 사용하여 다운스트림 AWS 서비스 또는 리소스를 호출할 때마다 SDK는 하위 세그먼트에 호출에 대한 정보를 기록합니다. 서비스 내에서 액세스하는 AWS 서비스 리소스는 트레이스 맵에 다운스트림 노드로 표시되어 개별 연결에서 오류 및 제한 문제를 식별하는 데 도움이 됩니다.
모든 다운스트림 호출을 계측하지 않으려면 계측기 하위 모듈을 생략하고 계측할 클라이언트를 선택할 AWS 서비스수 있습니다. AWS SDK 서비스 클라이언트에 [를 추가하여 `TracingHandler`](xray-sdk-java-awssdkclients.md) 개별 클라이언트를 계측합니다.
다른 Java용 X-Ray SDK 하위 모듈은 HTTP web API 및 SQL 데이터베이스에 대한 다운스트림 호출을 계측합니다. Apache HTTP 하위 모듈의 [Java용 X-Ray SDK 버전 `HTTPClient`와 `HTTPClientBuilder`를 사용](xray-sdk-java-httpclients.md)하여 Apache HTTP 클라이언트를 계측할 수 있습니다. SQL 쿼리를 구성하려면 [SDK의 인터셉터를 데이터 원본에 추가](xray-sdk-java-sqlclients.md)합니다.
SDK를 사용하기 시작한 후에, [레코더와 servlet 필터를 구성](xray-sdk-java-configuration.md)하여 SDK 동작을 구성하십시오. 플러그인을 추가해 애플리케이션을 실행하는 컴퓨팅 리소스에 대한 데이터를 기록하고, 샘플링 규칙을 정의해 샘플링 동작을 구성하고, 로그 레벨을 설정해 애플리케이션 로그의 SDK에서 표시되는 정보 수준을 조절할 수 있습니다.
요청에 대한 추가 정보와 애플리케이션이 [주석 및 메타데이터](xray-sdk-java-segment.md)에서 하는 작업을 기록합니다. 주석은 [필터 표현식](xray-console-filters.md)과 함께 사용할 수 있도록 인덱싱된 단순한 키 값 쌍이기 때문에, 특정 데이터를 포함한 트레이스를 검색할 수 있습니다. 메타데이터 항목은 제한이 적으며 JSON으로 직렬화할 수 있는 모든 객체와 어레이를 기록할 수 있습니다.
**주석 및 메타데이터**
주석 및 메타데이터는 X SDK를 사용하여 세그먼트에 추가하는 임의의 텍스트입니다. 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 메타데이터는 인덱싱되지 않지만 X-Ray 콘솔 또는 API를 사용하여 원시 세그먼트에서 볼 수 있습니다. X-Ray에 대한 읽기 액세스가 부여된 사용자는 누구나 이 데이터를 볼 수 있습니다.
코드에 계측된 클라이언트가 많다면, 계측된 클라이언트로 만든 각 요청의 하위 세그먼트를 대량으로 보관하는 요청 세그먼트 하나를 만들 수 있습니다. [사용자 지정 하위 세그먼트](xray-sdk-java-subsegments.md)의 클라이언트 호출을 래핑해 하위 세그먼트를 조직하고 그룹화할 수 있습니다. 전체 함수나 특정 코드 부분에 대한 사용자 지정 하위 세그먼트를 만들고, 상위 세그먼트에 모든 것을 적는 대신 하위 세그먼트에 메타데이터와 주석을 기록할 수 있습니다.
## 하위 모듈
Maven에서 Java용 X-Ray SDK를 다운로드할 수 있습니다. Java용 X-Ray SDK는 사용 사례별로 하위 모듈로 나뉘며, 버전 관리용 BOM을 포함합니다:
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/) (필수) – 세그먼트 생성 및 세그먼트 전송을 위한 기본 기능. 수신 요청 구성을 위한 `AWSXRayServletFilter`를 포함합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/) - 추적 AWS SDK for Java 클라이언트를 요청 핸들러로 추가하여 클라이언트에 AWS 서비스 대한 호출을 계측합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/) - 추적 클라이언트를 요청 인터셉터로 추가하여 AWS SDK for Java 2.2 이상 클라이언트에서 AWS 서비스 수행된 호출을 계측합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/) - `aws-xray-recorder-sdk-aws-sdk`를 사용하여 모든 AWS SDK for Java 클라이언트를 자동으로 계측합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/) - `aws-xray-recorder-sdk-aws-sdk-v2`를 사용하여 모든 AWS SDK for Java 2.2 이상 클라이언트를 자동으로 계측합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/) – Apache HTTP 클라이언트에서 생성된 발신 HTTP 호출을 구성합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/) – Spring AOP 프레임워크 애플리케이션의 인터셉터를 제공합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/) – JDBC에서 생성된 PostgreSQL 데이터베이스에 대한 발신 호출을 구성합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/) – JDBC에서 생성된 MySQL 데이터베이스에 대한 발신 호출을 구성합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/) – 모든 하위 모듈에 사용할 버전을 지정하는 데 사용할 수 있는 BOM을 제공합니다.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/) – 수집된 X-Ray 세그먼트에서 샘플링되지 않은 Amazon CloudWatch 지표를 게시합니다.
Maven 또는 Gradle을 사용하여 애플리케이션을 빌드하는 경우, [빌드 구성에 Java용 X-Ray SDK를 추가합니다](#xray-sdk-java-dependencies).
SDK의 클래스 및 메서드에 대한 참조 문서는 [Java용AWS X-Ray SDK API Reference](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc)를 참조하십시오.
## 요구 사항
Java용 X-Ray SDK에는 Java 8 이상, Servlet API 3, AWS SDK 및 Jackson이 필요합니다.
SDK는 컴파일 및 실행 시간 시 다음 라이브러리에 의존합니다.
+ AWS SDK for Java 버전 1.11.398 이상
+ Servlet API 3.1.0
이러한 종속성은 SDK의 `pom.xml` 파일에서 선언되며 Maven 또는 Gradle을 사용하여 빌드하는 경우 자동으로 포함됩니다.
Java용 X-Ray SDK에 포함된 라이브러리를 사용하는 경우 포함된 버전을 사용해야 합니다. 예를 들어 실행 시간 시 이미 Jackson에 의존하고 해당 종속성을 위해 배포에 JAR 파일을 포함시킨 경우에는 SDK JAR이 자체 버전의 Jackson 라이브러리를 포함하므로 이들 JAR 파일을 제거해야 합니다.
## 종속성 관리
Java용 X-Ray SDK는 Maven에서 사용할 수 있습니다.
+ **그룹** – `com.amazonaws`
+ **아티팩트** – `aws-xray-recorder-sdk-bom`
+ **버전** – `2.11.0`
Maven을 사용하여 애플리케이션을 빌드하는 경우 `pom.xml` 파일에서 SDK를 종속성으로 추가합니다.
**Example pom.xml - 종속성**
```
com.amazonaws
aws-xray-recorder-sdk-bom
2.11.0
pom
import
com.amazonaws
aws-xray-recorder-sdk-core
com.amazonaws
aws-xray-recorder-sdk-apache-http
com.amazonaws
aws-xray-recorder-sdk-aws-sdk
com.amazonaws
aws-xray-recorder-sdk-aws-sdk-instrumentor
com.amazonaws
aws-xray-recorder-sdk-sql-postgres
com.amazonaws
aws-xray-recorder-sdk-sql-mysql
```
Gradle의 경우, `build.gradle` 파일에서 SDK를 컴파일 시점 종속성으로 추가합니다.
**Example build.gradle - 종속성**
```
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
compile("com.amazonaws:aws-java-sdk-dynamodb")
compile("com.amazonaws:aws-xray-recorder-sdk-core")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor")
compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
testCompile("junit:junit:4.11")
}
dependencyManagement {
imports {
mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
}
}
```
Elastic Beanstalk를 사용하여 애플리케이션을 배포하는 경우, 모든 종속 요소를 포함하는 대규모 아카이브를 빌드하고 업로드하는 대신 배포할 때마다 Maven 또는 Gradle을 사용하여 온-인스턴스를 빌드할 수 있습니다. Gradle 사용 예시를 보려면 [샘플 애플리케이션](xray-scorekeep.md)을 참조하십시오.
# AWS X-Ray Java용 자동 계측 에이전트
**참고**
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)을 참조하세요.
Java용 AWS X-Ray 자동 계측 에이전트는 최소한의 개발 노력으로 Java 웹 애플리케이션을 계측하는 추적 솔루션입니다. 이 에이전트는 서블릿 기반 애플리케이션과 지원되는 프레임워크 및 라이브러리로 이루어진 에이전트의 모든 다운스트림 요청에 대한 추적을 지원합니다. 여기에는 다운스트림 Apache HTTP 요청, AWS SDK 요청 및 JDBC 드라이버를 사용하여 만든 SQL 쿼리가 포함됩니다. 에이전트는 모든 활성 세그먼트와 하위 세그먼트를 포함한 X-Ray 컨텍스트를 스레드 전체에 전파합니다. X-Ray SDK의 모든 구성과 다양한 기능을 Java 에이전트에서 계속 사용할 수 있습니다. 에이전트가 최소한의 노력으로 작업할 수 있도록 적절한 기본값이 선택되었습니다.
X-Ray 에이전트 솔루션은 서블릿 기반의 요청-응답 Java 웹 애플리케이션 서버에 가장 적합합니다. 애플리케이션이 비동기 프레임워크를 사용하거나 요청-응답 서비스로 잘 모델링되지 않은 경우, SDK를 사용한 수동 계측을 대신 고려할 수 있습니다.
X-Ray 에이전트는 분산 시스템 이해 툴킷(DiSCo)을 사용하여 구축됩니다. DiSCo는 분산 시스템에서 사용할 수 있는 Java 에이전트를 구축하기 위한 오픈 소스 프레임워크입니다. X-Ray 에이전트를 사용하기 위해 DisCo를 이해할 필요는 없지만 [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 에이전트로 계측할 수 있도록 조정되었습니다. 이러한 기능은 에이전트가 수행하므로 이 브랜치에는 서블릿 필터나 레코더 구성이 포함되어 있지 않습니다. 애플리케이션을 로컬에서 실행하거나 AWS 리소스를 사용하여 실행하려면 샘플 애플리케이션의 readme 파일에 있는 단계를 따르세요. 샘플 앱을 사용하여 X-Ray 트레이스를 생성하는 방법은 [샘플 앱의 튜토리얼](xray-scorekeep.md)에 나와 있습니다.
## 시작하기
자체 애플리케이션에서 X-Ray 자동 계측 Java 에이전트를 시작하려면 다음 절차를 따르십시오.
1. 사용 중인 환경에서 X-Ray 대몬(daemon)을 실행합니다. 자세한 내용은 [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 인수가 다음을 포함하도록 수정하여 에이전트를 활성화합니다. 해당하는 경우 `-jar` 인수 *앞에* `-javaagent` 인수를 배치해야 합니다. 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)을 참조하십시오.
## 구성
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
}
```
### 구성 사양
다음 표에서는 각 속성의 유효한 값에 대해 설명합니다. 속성 이름은 대소문자를 구분하지만 키는 대소문자를 구분하지 않습니다. 환경 변수 및 시스템 속성으로 재정의할 수 있는 속성의 경우 우선 순위는 항상 환경 변수, 시스템 속성, 구성 파일 순입니다. 재정의할 수 있는 속성에 대한 자세한 내용은 [환경 변수](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) 단원을 참조하세요. 모든 필드는 선택 사항입니다.
| 속성 이름 | Type | 유효값 | 설명 | 환경 변수 | 시스템 속성 | 기본값 |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | 문자열 | 모든 문자열 | X-Ray 콘솔에 표시되는 계측된 서비스의 이름 | AWS\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.Strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | 문자열 | LOG\$1ERROR, IGNORE\$1ERROR | 에이전트가 X-Ray 세그먼트 컨텍스트를 사용하려고 시도했지만 아무것도 없을 때 에이전트가 취하는 작업입니다. | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.Strategy.Context Missing Strategy | LOG\$1ERROR |
| daemonAddress | 문자열 | 포맷된 IP 주소 및 포트 또는 TCP 및 UDP 주소 목록 | 에이전트가 X-Ray 대몬(daemon)과 통신하는 데 사용하는 주소입니다. | AWS\$1XRAY\$1DAEMON\$1ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1:2000 |
| tracingEnabled | 부울 | True, False | 엑스레이 에이전트에 의한 계측을 활성화합니다. | AWS\$1XRAY\$1TRACING\$1ENABLED | com.amazonaws.xray.tracingEnabled | TRUE |
| samplingStrategy | 문자열 | CENTRAL, LOCAL, NONE, ALL | 에이전트가 사용하는 샘플링 전략. ALL은 모든 요청을 캡처하고, NONE은 요청을 캡처하지 않습니다. [샘플링 규칙](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling)을 참조하세요. | 해당 사항 없음 | 해당 사항 없음 | CENTRAL |
| traceIdInjectionPrefix | 문자열 | 모든 문자열 | 로그에 트레이스 ID를 삽입하기 전에 제공된 접두사를 포함합니다. | 해당 사항 없음 | 해당 사항 없음 | 없음 (빈 문자열) |
| samplingRulesManifest | 문자열 | 절대 파일 경로 | 로컬 샘플링 전략에 대한 샘플링 규칙의 소스 또는 중앙 전략에 대한 대체 규칙으로 사용할 사용자 지정 샘플링 규칙 파일의 경로입니다. | 해당 사항 없음 | 해당 사항 없음 | [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 | 문자열 | 절대 파일 경로 | AWS SDK 클라이언트로부터 추가 정보를 캡처하는 사용자 지정 매개변수 허용 목록의 경로입니다. | 해당 사항 없음 | 해당 사항 없음 | [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 | 사용 중인 [Java용AWS SDK](https://docs.aws.amazon.com/sdk-for-java/index.html) 버전입니다. `awsServiceHandlerManifest`이 설정되지 않은 경우 무시됩니다. | 해당 사항 없음 | 해당 사항 없음 | 2 |
| maxStackTraceLength | 정수 | 음수가 아닌 정수 | 트레이스에 기록할 스택 트레이스의 최대 줄 수입니다. | 해당 사항 없음 | 해당 사항 없음 | 50 |
| streamingThreshold | 정수 | 음수가 아닌 정수 | 최소한 이만큼의 서브세그먼트가 닫힌 후에는 청크가 너무 커지는 것을 방지하기 위해 아웃오브밴드 (out-of-band) 대몬(daemon)으로 스트리밍됩니다. | 해당 사항 없음 | 해당 사항 없음 | 100 |
| traceIdInjection | 부울 | True, False | [로깅 구성](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)에 설명된 종속성 및 구성도 추가된 경우 로그에 X-Ray trace ID 삽입을 활성화합니다. 그렇지 않으면 아무 작업도 수행하지 않습니다. | 해당 사항 없음 | 해당 사항 없음 | TRUE |
| pluginsEnabled | 부울 | True, False | 운영 중인 AWS 환경에 대한 메타데이터를 기록하는 플러그인을 활성화합니다. [플러그인](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins)을 참조하십시오. | 해당 사항 없음 | 해당 사항 없음 | TRUE |
| collectSqlQueries | 부울 | True, False | SQL 쿼리 문자열을 SQL 하위 세그먼트에 최선을 다해 기록합니다. | 해당 사항 없음 | 해당 사항 없음 | FALSE |
| contextPropagation | 부울 | True, False | true인 경우 스레드 간에 X-Ray 컨텍스트를 자동으로 전파합니다. 그렇지 않으면 Thread Local을 사용하여 컨텍스트를 저장하고 스레드 간 수동 전파가 필요합니다. | 해당 사항 없음 | 해당 사항 없음 | TRUE |
### 로깅 구성
X-Ray 에이전트의 로그 수준은 Java용 X-Ray SDK와 동일한 방식으로 구성할 수 있습니다. Java용 X-Ray SDK를 사용하여 로깅을 구성하는 방법에 대한 자세한 내용은 [로깅](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)를 참조하십시오.
### 수동 구성
에이전트의 자동 계측 외에도 수동 계측을 수행하려는 경우 프로젝트에 종속 항목으로 X-Ray SDK를 추가하세요. [수신 요청 추적](xray-sdk-java-filters.md)에서 언급한 SDK의 사용자 지정 서블릿 필터는 X-Ray 에이전트와 호환되지 않는다는 점에 유의하십시오.
**참고**
에이전트를 사용하는 동시에 수동 계측을 수행하려면 최신 버전의 X-Ray SDK를 사용해야 합니다.
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'
```
에이전트를 사용하는 동안 일반 SDK와 마찬가지로 [주석, 메타데이터, 사용자 ID](xray-sdk-java-segment.md) 외에도 [사용자 지정 하위 세그먼트](xray-sdk-java-subsegments.md)를 추가할 수 있습니다. 에이전트는 스레드 간에 컨텍스트를 자동으로 전파하므로 멀티스레드 애플리케이션에서 작업할 때는 컨텍스트를 전파하기 위한 해결 방법이 필요하지 않습니다.
## 문제 해결
에이전트는 완전 자동 계측 기능을 제공하기 때문에 문제가 발생했을 때 문제의 근본 원인을 파악하기 어려울 수 있습니다. X-Ray 에이전트가 예상대로 작동하지 않는 경우 다음 문제와 해결 방법을 검토하세요. X-Ray 에이전트와 SDK는 자카르타 커먼즈 로깅 (JCL) 을 사용합니다. 로깅 출력을 보려면 다음 예제와 같이 JCL을 로깅 백엔드에 연결하는 브리지가 클래스 경로에 있는지 확인하십시오. `log4j-jcl` 또는 `jcl-over-slf4j`
### 문제: 애플리케이션에서 Java 에이전트를 활성화했지만 X-Ray 콘솔에 아무 것도 표시되지 않습니다.
**X-Ray 대몬(daemon)이 동일한 시스템에서 실행되고 있습니까?**
그렇지 않은 경우, [X-Ray 대몬(daemon) 설명서](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)을 참조하십시오.
# Java용 X-Ray SDK 구성
**참고**
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)을 참조하세요.
Java용 X-Ray SDK에는 전역 레코더를 제공하는 `AWSXRay`라는 클래스가 있습니다. 이는 코드를 구성하는 데 사용할 수 있는 `TracingHandler`입니다. 전역 레코더를 구성하여 수신 HTTP 호출에 대해 세그먼트를 생성하는 `AWSXRayServletFilter`를 사용자 지정할 수 있습니다.
**Topics**
+ [서비스 플러그인](#xray-sdk-java-configuration-plugins)
+ [샘플링 규칙](#xray-sdk-java-configuration-sampling)
+ [로깅](#xray-sdk-java-configuration-logging)
+ [세그먼트 리스너](#xray-sdk-java-configuration-listeners)
+ [환경 변수](#xray-sdk-java-configuration-envvars)
+ [시스템 속성](#xray-sdk-java-configuration-sysprops)
## 서비스 플러그인
`plugins`을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.
**플러그인**
+ Amazon EC2 — `EC2Plugin`은 인스턴스 ID, 가용 영역 및 CloudWatch Logs 그룹을 추가합니다.
+ Elastic Beanstalk – `ElasticBeanstalkPlugin`이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
+ Amazon ECS — `ECSPlugin`이 컨테이너 ID를 추가합니다.
+ Amazon EKS – `EKSPlugin`은 컨테이너 ID, 클러스터 이름, 포드 ID 및 CloudWatch Logs 그룹을 추가합니다.
![\[Amazon EC2 및 Elastic Beanstalk 플러그인으로 리소스 데이터를 세분화하세요.\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png)
플러그인을 사용하려면 `AWSXRayRecorderBuilder`에서 `withPlugin`을 호출하십시오.
**Example src/main/java/scorekeep/WebConfig.java - 레코더**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
SDK는 플러그인 설정을 사용하여 세그먼트에 `origin` 필드를 설정하기도 합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK는 ElasticBeanstalk> EKS> ECS> EC2 순서로 확인하여 오리진을 결정합니다.
## 샘플링 규칙
SDK는 X-Ray 콘솔에서 정의하는 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. [X-Ray 콘솔에서 추가 규칙을 생성](xray-console-sampling.md)하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.
SDK는 사용자 지정 규칙을 정의된 순서대로 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 SDK는 첫 번째 규칙만 적용합니다.
**참고**
SDK가 샘플링 규칙을 가져오기 위해 X-Ray에 연결할 수 없는 경우, 매초 첫 번째 요청과 호스트당 추가 요청의 5%에 대한 기본 로컬 규칙으로 되돌아갑니다. 호스트가 샘플링 API를 직접 호출할 수 있는 권한이 없거나, X-Ray 대몬(daemon)에 연결할 수 없을 경우 이러한 상황이 발생할 수 있고 이 대몬(daemon)은 SDK에서 수행한 API 직접 호출에 대한 TCP 프록시 역할을 합니다.
JSON 문서에서 샘플링 규칙을 불러오도록 SDK를 구성할 수도 있습니다. SDK는 X-Ray 샘플링을 사용할 수 없을 경우 로컬 규칙을 백업으로 사용하거나, 로컬 규칙을 전용으로 사용할 수 있습니다.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
이 예에서는 하나의 사용자 지정 규칙과 기본 규칙을 정의합니다. 사용자 지정 규칙은 최소 추적 요청 수 없이 5% 샘플링 비율을 `/api/move/` 아래 경로에 적용합니다. 기본 규칙은 매초 최초 요청과 추가 요청의 10%를 추적합니다.
로컬로 규칙의 정의할 때의 단점은 고정 대상이 X-Ray 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.
에서는 샘플링 속도를 수정할 수 AWS Lambda없습니다. 구성된 서비스가 함수를 호출하는 경우 해당 서비스에서 샘플링한 요청을 생성한 호출이 Lambda에 의해 기록됩니다. 활성 추적이 활성화되고 트레이스 헤더가 없는 경우 Lambda에서 샘플링 결정을 내립니다.
Spring에서 백업 규칙을 제공하려면 구성 클래스에서 `CentralizedSamplingStrategy`를 사용하여 전역 레코더를 구성합니다.
**Example src/main/java/myapp/WebConfig.java – 레코더 구성**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
```
Tomcat의 경우 `ServletContextListener`를 확장하는 리스너를 추가하고 이 리스너를 배포 설명자에 등록합니다.
**Example src/com/myapp/web/Startup.java**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent event) {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
@Override
public void contextDestroyed(ServletContextEvent event) { }
}
```
**Example WEB-INF/web.xml**
```
...
com.myapp.web.Startup
```
로컬 규칙만 사용하려면 `CentralizedSamplingStrategy`를 `LocalizedSamplingStrategy`로 바꿉니다.
```
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
```
## 로깅
기본적으로 이 SDK는 `ERROR` 수준 및 수준 메시지를 애플리케이션 로그로 출력합니다. SDK에 대한 디버그 수준 로깅을 활성화하여 보다 상세한 로그를 애플리케이션 로그 파일로 출력할 수 있습니다. 유효한 로그 수준은`DEBUG`, `INFO`, `WARN`, `ERROR`, 및 `FATAL`입니다. `FATAL` 로그 수준은 SDK가 치명적 수준에서 로깅하지 않기 때문에 모든 로그 메시지를 무음 처리합니다.
**Example 애플리케이션 속성**
`logging.level.com.amazonaws.xray` 속성을 사용하여 로깅 수준을 설정합니다.
```
logging.level.com.amazonaws.xray = DEBUG
```
디버그 로그를 사용하여 [수동으로 하위 세그먼트를 생성](xray-sdk-java-subsegments.md)할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.
### 로그에 추적 ID 주입
현재 정규화된 트레이스 ID를 로그 문에 표시하려면 매핑된 진단 컨텍스트(MDC)에 해당 ID를 주입할 수 있습니다. 메서드는 `SegmentListener` 인터페이스를 사용하여 세그먼트 수명 주기 이벤트 중에 X-Ray 레코더에서 호출됩니다. 세그먼트 또는 하위 세그먼트가 시작되면 정규화된 트레이스 ID가 `AWS-XRAY-TRACE-ID` 키를 사용하여 MDC에 주입됩니다. 해당 세그먼트가 끝나면 MDC에서 키가 제거됩니다. 이렇게 하면 사용 중인 로깅 라이브러리에 트레이스 ID가 표시됩니다. 하위 세그먼트가 끝나면 부모 ID가 MDC에 주입됩니다.
**Example 정규화된 트레이스 ID**
정규화된 ID는 `TraceID@EntityID`로 표시됩니다.
```
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3
```
이 기능은 Java용 AWS X-Ray SDK로 구성된 Java 애플리케이션에서 작동하며 다음 로깅 구성을 지원합니다.
+ Logback 백엔드가 있는 SLF4J 프런트 엔드 API
+ Log4J2 백엔드가 있는 SLF4J 프런트 엔드 API
+ Log4J2 백엔드가 있는 Log4J2 프런트 엔드 API
각 프런트 엔드와 각 백엔드의 요구 사항은 다음 탭을 참조하십시오.
------
#### [ SLF4J Frontend ]
1. 다음 Maven 종속성을 프로젝트에 추가합니다.
```
com.amazonaws
aws-xray-recorder-sdk-slf4j
2.11.0
```
1. `AWSXRayRecorder`를 구축할 때 `withSegmentListener` 메서드를 포함시킵니다. 이렇게 하면 새 트레이스 ID를 SLF4J MDC에 자동으로 주입하는 `SegmentListener` 클래스가 추가됩니다.
`SegmentListener`는 선택적 문자열을 파라미터로 사용하여 log 문 접두사를 구성합니다. 접두사는 다음과 같은 방법으로 구성할 수 있습니다.
+ **없음** – 기본 `AWS-XRAY-TRACE-ID` 접두사를 사용합니다.
+ **비어 있음** – 빈 문자열(예: `""`)을 사용합니다.
+ **사용자 지정** – 문자열에 정의된 사용자 지정 접두사를 사용합니다.
**Example `AWSXRayRecorderBuilder` 명령문**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Log4J2 front end ]
1. 다음 Maven 종속성을 프로젝트에 추가합니다.
```
com.amazonaws
aws-xray-recorder-sdk-log4j
2.11.0
```
1. `AWSXRayRecorder`를 구축할 때 `withSegmentListener` 메서드를 포함시킵니다. 이렇게 하면 새 정규화된 트레이스 ID를 SLF4J MDC에 자동으로 주입하는 `SegmentListener` 클래스가 추가됩니다.
`SegmentListener`는 선택적 문자열을 파라미터로 사용하여 log 문 접두사를 구성합니다. 접두사는 다음과 같은 방법으로 구성할 수 있습니다.
+ **없음** – 기본 `AWS-XRAY-TRACE-ID` 접두사를 사용합니다.
+ **비어 있음** – 빈 문자열(예: `""`)을 사용하고 접두사를 제거합니다.
+ **사용자 지정** – 문자열에 정의된 사용자 지정 접두사를 사용합니다.
**Example `AWSXRayRecorderBuilder` 명령문**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Logback backend ]
트레이스 ID를 로그 이벤트에 삽입하려면 각 로깅 문의 형식을 지정하는 로거의 `PatternLayout`을 수정해야 합니다.
1. `patternLayout`이 구성된 위치를 찾습니다. 이 작업은 프로그래밍 방식으로 또는 XML 구성 파일을 통해 수행할 수 있습니다. 자세한 내용은 [Logback 구성](http://logback.qos.ch/manual/configuration.html)을 참조하십시오.
1. 이후 로깅 문에 트레이스 ID를 삽입하려면 `patternLayout`의 아무 곳에나 `%X{AWS-XRAY-TRACE-ID}`를 삽입합니다. `%X{}`는 MDC에서 제공된 키를 사용해 값을 검색하고 있음을 나타냅니다. Logback의 PatternLayout에 대한 자세한 내용은 [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout)을 참조하십시오.
------
#### [ Log4J2 backend ]
1. `patternLayout`이 구성된 위치를 찾습니다. 이 작업은 XML, JSON, YAML 또는 속성 형식으로 작성된 구성 파일을 통해 또는 프로그래밍 방식으로 수행할 수 있습니다.
구성 파일을 통해 Log4J2를 구성하는 방법에 대한 자세한 내용은 [구성](https://logging.apache.org/log4j/2.x/manual/configuration.html)을 참조하십시오.
프로그래밍 방식으로 Log4J2를 구성하는 방법에 대한 자세한 내용은 [프로그래밍 방식으로 구성](https://logging.apache.org/log4j/2.x/manual/customconfig.html)을 참조하십시오.
1. 이후 로깅 문에 트레이스 ID를 삽입하려면 `PatternLayout`의 아무 곳에나 `%X{AWS-XRAY-TRACE-ID}`를 삽입합니다. `%X{}`는 MDC에서 제공된 키를 사용해 값을 검색하고 있음을 나타냅니다. Log4J2의 PatternLayout에 대한 자세한 내용은 [PatternLayout](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout)을 참조하십시오.
------
**트레이스 ID 주입 예제**
다음은 트레이스 ID를 포함하도록 수정된 `PatternLayout` 문자열을 보여줍니다. 트레이스 ID는 스레드 이름(`%t`) 뒤에 및 로그 레벨(`%-5p`) 앞에 인쇄됩니다.
**Example ID 주입이 있는 `PatternLayout`**
```
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n
```
AWS X-Ray 는 쉽게 구문 분석할 수 있도록 로그 문에 키와 추적 ID를 자동으로 인쇄합니다. 다음은 수정된 `PatternLayout`을 사용하는 로그 문을 보여줍니다.
**Example ID 주입이 있는 로그 문**
```
2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here
```
로깅 메시지 자체는 패턴 `%m`에 보관되며 로거를 호출할 때 설정됩니다.
## 세그먼트 리스너
세그먼트 리스너는 `AWSXRayRecorder`에 의해 생성된 세그먼트의 시작 및 끝과 같은 수명 주기 이벤트를 가로챌 수 있는 인터페이스입니다. 세그먼트 리스너 이벤트 함수의 구현은 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-)로 생성될 때 모든 하위 세그먼트에 동일한 주석을 추가하거나, [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-)를 사용하여 각 세그먼트를 대몬에 전송한 후 메시지를 기록하거나, [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-)를 사용하여 SQL 인터셉터가 전송한 쿼리를 기록하여 하위 세그먼트가 SQL 쿼리를 나타내는지 확인하고, 그렇다면 추가적인 메타데이터를 추가합니다.
전체 `SegmentListener` 함수 목록을 보려면 [AWS X-Ray X-Ray Recorder SDK for Java API](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html)에 대한 설명서를 참조하십시오.
다음 예제에서는 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-)를 사용하여 생성할 때 모든 하위 세그먼트에 일관된 주석을 추가하고 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-)를 사용하여 각 세그먼트의 끝에 로그 메시지를 인쇄하는 방법을 보여줍니다.
**Example MySegmentListener.java**
```
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;
public class MySegmentListener implements SegmentListener {
.....
@Override
public void onBeginSubsegment(Subsegment subsegment) {
subsegment.putAnnotation("annotationKey", "annotationValue");
}
@Override
public void afterEndSegment(Segment segment) {
// Be mindful not to mutate the segment
logger.info("Segment with ID " + segment.getId());
}
}
```
이 사용자 지정 세그먼트 리스너는 `AWSXRayRecorder`를 빌드할 때 참조됩니다.
**Example AWSXRayRecorderBuilder 문**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new MySegmentListener());
```
## 환경 변수
환경 변수를 사용하여 Java용 X-Ray SDK를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.
+ `AWS_XRAY_CONTEXT_MISSING` – 열려 있는 세그먼트가 없는 경우 구성된 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `RUNTIME_ERROR`로 설정합니다.
**유효한 값**
+ `RUNTIME_ERROR`— 런타임 예외가 발생합니다.
+ `LOG_ERROR` – 오류를 기록하고 계속합니다 (기본값).
+ `IGNORE_ERROR`— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 SDK는 추적 데이터(UDP)와 샘플링(TCP) 모두에 `127.0.0.1:2000`을 사용합니다. [다른 포트에서 수신 대기](xray-daemon-configuration.md)하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
**형식**
+ **동일한 포트** – `address:port`
+ **다른 포트** – `tcp:address:port udp:address:port`
+ `AWS_LOG_GROUP` - 로그 그룹의 이름을 애플리케이션과 연결된 로그 그룹으로 설정합니다. 로그 그룹이 애플리케이션과 동일한 AWS 계정 및 리전을 사용하는 경우 X-Ray는이 지정된 로그 그룹을 사용하여 애플리케이션의 세그먼트 데이터를 자동으로 검색합니다. 로그 그룹에 대한 자세한 내용은 [로그 그룹 및 스트림 작업](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)을 참조하세요.
+ `AWS_XRAY_TRACING_NAME` – SDK가 세그먼트에 사용할 서비스 이름을 설정합니다. 서블릿 필터의 [세그먼트 이름 지정 전략](xray-sdk-java-filters.md#xray-sdk-java-filters-naming)에 설정한 서비스 이름을 재정의합니다.
환경 변수는 코드에 설정된 동등한 [시스템 속성](#xray-sdk-java-configuration-sysprops) 및 값을 재정의합니다.
## 시스템 속성
시스템 속성을 [환경 변수](#xray-sdk-java-configuration-envvars)에 대한 JVM 지정 대체로 사용할 수 있습니다. SDK는 다음 속성을 지원합니다.
+ `com.amazonaws.xray.strategy.tracingName` – `AWS_XRAY_TRACING_NAME`와 동등합니다.
+ `com.amazonaws.xray.emitters.daemonAddress` – `AWS_XRAY_DAEMON_ADDRESS`와 동등합니다.
+ `com.amazonaws.xray.strategy.contextMissingStrategy` – `AWS_XRAY_CONTEXT_MISSING`와 동등합니다.
시스템 속성과 환경 변수가 모두 설정될 경우 환경 변수 값이 사용됩니다. 어느 방법도 코드에 설정된 값을 재정의합니다.
# Java용 X-Ray SDK로 수신 요청 추적하기
**참고**
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)을 참조하세요.
X-Ray SDK를 사용하여 애플리케이션이 Amazon EC2 AWS Elastic Beanstalk또는 Amazon ECS의 EC2 인스턴스에서 처리하는 수신 HTTP 요청을 추적할 수 있습니다.
`Filter`를 사용하여 수신 HTTP 요청을 구성합니다. 애플리케이션에 X-Ray 서블릿 필터를 추가하면 Java용 X-Ray SDK가 샘플링된 각 요청에 대해 세그먼트를 생성합니다. 이 세그먼트에는 HTTP 요청의 시간, 메서드 및 배치가 포함됩니다. 추가로 구성하면 이 세그먼트의 하위 세그먼트가 생성됩니다.
**참고**
AWS Lambda 함수의 경우 Lambda는 샘플링된 각 요청에 대한 세그먼트를 생성합니다. 자세한 정보는 [AWS Lambda 및 AWS X-Ray](xray-services-lambda.md)을 참조하세요.
각 세그먼트에는 서비스 맵 안에서 애플리케이션을 식별하는 이름이 있습니다. 이 세그먼트의 이름이 정적으로 지정되도록 하거나, 수신 요청의 호스트 헤더를 기반으로 SDK가 동적으로 이름을 지정하도록 구성할 수 있습니다. 동적 이름 지정을 사용하면 요청의 도메인 이름에 따라 그룹을 추적하고 이름이 예상 패턴과 일치하지 않을 경우(예: 호스트 헤더가 위조된 경우) 기본 이름을 적용할 수 있습니다.
**전달된 요청**
로드 밸런서 또는 기타 중개자가 애플리케이션으로 요청을 전달하는 경우, X-Ray는 IP 패킷 내 소스 IP가 아니라 요청의 `X-Forwarded-For` 헤더로부터 클라이언트 IP를 가져옵니다. 전달된 요청에 대해 기록된 클라어언트 IP는 위조될 수 있으므로 신뢰하면 안 됩니다.
요청이 전달되면 SDK는 세그먼트에 추가 필드를 설정하여 이를 나타냅니다. 세그먼트에 `x_forwarded_for`로 설정된 `true` 필드가 포함된 경우 클라이언트 IP는 HTTP 요청의 `X-Forwarded-For` 헤더로부터 가져옵니다.
메시지 핸들러는 다음 정보를 포함하는 `http` 블록을 이용해 각 수신 요청에 대한 세그먼트를 생성합니다.
+ **HTTP 메서드** – GET, POST, PUT, DELETE 등.
+ **클라이언트 주소** – 요청을 전송한 클라이언트의 IP 주소.
+ **응답 코드** – 완료된 요청의 HTTP 응답 코드.
+ **시간** – 시작 시간(요청 수신) 및 종료 시간(응답 전송).
+ **유저 에이전트** — 요청에서 가져온 `user-agent`입니다.
+ **콘텐츠 길이** — 응답의 `content-length`입니다.
**Topics**
+ [애플리케이션에 추적 필터 추가(Tomcat)](#xray-sdk-java-filters-tomcat)
+ [애플리케이션에 추적 필터 추가(Spring)](#xray-sdk-java-filters-spring)
+ [세그먼트 이름 지정 전략 구성](#xray-sdk-java-filters-naming)
## 애플리케이션에 추적 필터 추가(Tomcat)
Tomcat의 경우, ``를 프로젝트의 `web.xml` 파일에 추가합니다. `fixedName` 파라미터로 수신 요청을 위해 생성된 세그먼트에 적용할 [서비스 이름](#xray-sdk-java-filters-naming)을 지정하십시오.
**Example WEB-INF/web.xml – Tomcat**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
fixedName
MyApp
AWSXRayServletFilter
*
```
## 애플리케이션에 추적 필터 추가(Spring)
Spring의 경우, `Filter`를 `WebConfig` 클래스에 추가합니다. 세그먼트 이름을 하나의 문자열로 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 생성자에 보냅니다.
**Example src/main/java/myapp/WebConfig.java - spring**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## 세그먼트 이름 지정 전략 구성
AWS X-Ray 는 *서비스 이름을* 사용하여 애플리케이션을 식별하고 애플리케이션이 사용하는 다른 애플리케이션, 데이터베이스, 외부 APIs 및 AWS 리소스와 구분합니다. X-Ray SDK는 수신 요청에 대한 세그먼트를 생성할 때 해당 세그먼트의 [이름 필드](xray-api-segmentdocuments.md#api-segmentdocuments-fields)에 애플리케이션의 서비스 이름을 기록합니다.
X-Ray SDK는 HTTP 요청 헤더의 호스트 이름 뒤에 세그먼트를 지정할 수 있습니다. 그러나 이 헤더가 위조되면 서비스 맵에 예기치 않은 노드가 발생할 수 있습니다. 위조된 호스트 헤더가 포함된 요청으로 인해 SDK가 잘못된 세그먼트 이름을 지정하는 현상을 방지하려면 들어오는 요청의 기본 이름을 지정해야 합니다.
애플리케이션이 여러 도메인의 요청을 처리하는 경우, 동적 이름 지정 전략을 사용하여 이를 세그먼트 이름에 반영하도록 SDK를 구성할 수 있습니다. 동적 이름 지정 전략을 사용하면 SDK가 예상 패턴과 일치하는 요청에 호스트 이름을 사용하고, 그렇지 않은 요청에 기본 이름을 적용할 수 있습니다.
예를 들어, 하나의 애플리케이션이 세 개의 하위 도메인 (`www.example.com`, `api.example.com`, `static.example.com`) 에 요청을 전송할 수 있습니다. `*.example.com` 패턴으로 동적 이름 지정 전략을 사용하여 각 하위도메인의 세그먼트를 서로 다른 이름으로 표시하면 서비스 맵에 서비스 노드가 세 개 생깁니다. 이 패턴에 맞지 않는 호스트 이름의 요청이 애플리케이션에 수신되면, 사용자가 지정한 대체 이름의 네 번째 노드가 서비스 맵에 표시됩니다.
모든 요청 세그먼트에 같은 이름을 사용하려면, [이전 단원](#xray-sdk-java-filters-tomcat)에 나온 것처럼 서블릿 필터를 초기화할 때 애플리케이션 이름을 지정하십시오. 이것은 `SegmentNamingStrategy.fixed()`를 호출하고 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 생성자에 전달하여 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)를 생성하는 것과 동일한 효과가 있습니다.
**참고**
코드에 정의한 기본 서비스 이름을 `AWS_XRAY_TRACING_NAME` [환경 변수](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)를 사용하여 재정의할 수 있습니다.
동적 이름 지정 전략은 호스트 이름이 일치해야 하는 패턴 및 HTTP 요청의 호스트 이름이 패턴과 일치하지 않는 경우 사용할 기본 이름을 정의합니다. Tomcat에서 세그먼트 이름을 동적으로 지정하려면, `dynamicNamingRecognizedHosts`와 `dynamicNamingFallbackName`을 이용해 패턴과 기본 이름을 따로 정의하십시오.
**Example WEB-INF/web.xml – 동적 이름 지정을 이용하는 서블릿 필터**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
dynamicNamingRecognizedHosts
*.example.com
dynamicNamingFallbackName
MyApp
AWSXRayServletFilter
*
```
Spring의 경우, `SegmentNamingStrategy.dynamic()`를 호출하여 동적 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)을 만들고 `AWSXRayServletFilter` 생성자로 보내십시오.
**Example src/main/java/myapp/WebConfig.java – 동적 이름 지정을 이용하는 서블릿 필터**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com"));
}
}
```
# Java용 X-Ray AWS SDK를 사용하여 SDK 호출 추적
**참고**
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)을 참조하세요.
애플리케이션이를 호출 AWS 서비스 하여 데이터를 저장하거나, 대기열에 쓰거나, 알림을 보내면 Java용 X-Ray SDK는 [하위 세그먼트](xray-sdk-java-subsegments.md)의 다운스트림 호출을 추적합니다. 추적된 AWS 서비스 와 해당 서비스(예: Amazon S3 버킷 또는 Amazon SQS 대기열) 내에서 액세스하는 리소스는 X-Ray 콘솔의 트레이스 맵에 다운스트림 노드로 표시됩니다.
빌드에서 `aws-sdk` 및 `aws-sdk-instrumentor` [하위 모듈](xray-sdk-java.md#xray-sdk-java-submodules)을 포함하면 Java용 X-Ray SDK가 모든 AWS SDK 클라이언트를 자동으로 계측합니다. Instrumentor 하위 모듈을 포함하지 않을 경우 다른 클라이언트는 배제하고 일부 클라이언트만 선택하여 구성할 수 있습니다.
개별 클라이언트를 계측하려면 빌드에서 `aws-sdk-instrumentor` 하위 모듈을 제거하고 서비스의 클라이언트 빌더를 사용하여 AWS SDK 클라이언트`TracingHandler`에를 `XRayClient`로 추가합니다.
예를 들어 `AmazonDynamoDB` 클라이언트를 구성하려면 트레이스 핸들러를`AmazonDynamoDBClientBuilder`로 전달합니다.
**Example MyModel.java - DynamoDB 클라이언트**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html);
...
public class MyModel {
private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.fromName(System.getenv("AWS_REGION")))
.withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
.build();
...
```
모든 서비스의 경우, X-Ray 콘솔에서 호출된 API의 이름을 볼 수 있습니다. 서비스 하위 집합에 대해서는 X-Ray SDK가 세그먼트에 정보를 추가하여 서비스 맵에서 추가 세분화를 제공합니다.
예를 들어 계측된 DynamoDB 클라이언트에서 직접 호출을 생성하는 경우 SDK가 특정 테이블을 대상으로 한 직접 호출에 대해 테이블 이름을 세그먼트에 추가합니다. 콘솔에서, 각 테이블이 개별 노드로 서비스 맵에 표시되고, 특정 테이블을 대상으로 하지 않은 직접 호출에 대해 일반 DynamoDB 노드가 표시됩니다.
**Example 항목을 저장하기 위한 DynamoDB 직접 호출에 대한 하위 세그먼트**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
명명된 리소스에 액세스할 때 다음 서비스를 호출할 경우 서비스 맵에 추가 노드가 생성됩니다. 특정 리소스를 대상으로 하지 않는 경우 서비스를 직접 호출하면 해당 서비스에 대한 일반 노드가 생성됩니다.
+ **Amazon DynamoDB** – 테이블 이름
+ **Amazon Simple Storage Service** –버킷 및 키 이름
+ **Amazon Simple Queue Service** – 대기열 이름
AWS SDK for Java 2.2 이상을 AWS 서비스 사용하여에 대한 다운스트림 호출을 계측하려면 빌드 구성에서 `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` 모듈을 생략할 수 있습니다. 대신 `aws-xray-recorder-sdk-aws-sdk-v2 module`을 포함한 다음, `TracingInterceptor`로 구성하여 개별 클라이언트를 계측합니다.
**Example AWS SDK for Java 2.2 이상 - 추적 인터셉터**
```
import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...
```
# Java용 X-Ray SDK를 사용하여 다운스트림 HTTP 웹 서비스에 대한 호출 추적하기
**참고**
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)을 참조하세요.
애플리케이션이 마이크로서비스 또는 공개 HTTP API를 호출할 때 Java용 X-Ray SDK 버전의 `HttpClient`를 사용하여 해당 호출을 계측하고 API를 다운스트림 서비스로 서비스 그래프에 추가할 수 있습니다.
Java용 X-Ray SDK는 발신 HTTP 호출을 계측하기 위해 Apache HttpComponents에 상응하는 클래스 대신 사용할 수 있는 `DefaultHttpClient` 및 `HttpClientBuilder` 클래스를 포함합니다.
+ `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient`
+ `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder`
이러한 라이브러리는 [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md) 하위 모듈에 있습니다.
모든 클라이언트를 계측하기 위해 기존 가져오기 문을 X-Ray에 해당하는 것으로 대체하거나, 특정 클라이언트를 계측하기 위해 클라이언트를 초기화할 때 정규화된 이름을 사용할 수 있습니다.
**Example HttpClientBuilder**
```
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html);
...
public String randomName() throws IOException {
CloseableHttpClient httpclient = HttpClientBuilder.create().build();
HttpGet httpGet = new HttpGet("http://names.example.com/api/");
CloseableHttpResponse response = httpclient.execute(httpGet);
try {
HttpEntity entity = response.getEntity();
InputStream inputStream = entity.getContent();
ObjectMapper mapper = new ObjectMapper();
Map jsonMap = mapper.readValue(inputStream, Map.class);
String name = jsonMap.get("name");
EntityUtils.consume(entity);
return name;
} finally {
response.close();
}
}
```
다운스트림 웹 API에 대한 직접 호출을 계측할 때 Java용 X-Ray SDK가 HTTP 요청 및 응답에 대한 정보가 포함된 하위 세그먼트를 기록합니다. X-Ray는 하위 세그먼트를 사용하여 원격 API에 대해 추정된 세그먼트를 생성합니다.
**Example 다운스트림 HTTP 호출에 대한 하위 세그먼트**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 다운스트림 HTTP 호출에 대한 추정된 세그먼트**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Java용 X-Ray SDK로 SQL 쿼리 추적하기
**참고**
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)을 참조하세요.
## SQL 인터셉터
Java용 X-Ray SDK JDBC 인터셉터를 데이터 소스 구성에 추가해 SQL 데이터베이스 쿼리를 계측하십시오.
+ **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor`
+ **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor`
이러한 인터셉터는 각각 [`aws-xray-recorder-sql-postgres` 및 `aws-xray-recorder-sql-mysql` 하위 모듈](xray-sdk-java.md)에 있습니다. 인터셉터는 `org.apache.tomcat.jdbc.pool.JdbcInterceptor`를 구현하며 Tomcat 연결 풀과 호환됩니다.
**참고**
SQL 인터셉터는 보안을 위해 하위 세그먼트 내에서 SQL 쿼리 자체를 기록하지 않습니다.
Spring인 경우에는 인터셉터를 속성 파일에 추가하고 Spring Boot의 `DataSourceBuilder`로 데이터 소스를 구축하십시오.
**Example `src/main/java/resources/application.properties` - PostgreSQL JDBC 인터셉터**
```
spring.datasource.continue-on-error=true
spring.jpa.show-sql=false
spring.jpa.hibernate.ddl-auto=create-drop
spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
```
**Example `src/main/java/myapp/WebConfig.java` - 데이터 소스**
```
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import javax.servlet.Filter;
import javax.sql.DataSource;
import java.net.URL;
@Configuration
@EnableAutoConfiguration
@EnableJpaRepositories("myapp")
public class RdsWebConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource")
public DataSource dataSource() {
logger.info("Initializing PostgreSQL datasource");
return DataSourceBuilder.create()
.driverClassName("org.postgresql.Driver")
.url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb")
.username(System.getenv("RDS_USERNAME"))
.password(System.getenv("RDS_PASSWORD"))
.build();
}
...
}
```
Tomcat의 경우에는 JDBC 데이터 소스에서 Java용 X-Ray SDK 클래스를 참조하여 `setJdbcInterceptors`를 직접 호출합니다.
**Example `src/main/myapp/model.java` - 데이터 소스**
```
import org.apache.tomcat.jdbc.pool.DataSource;
...
DataSource source = new DataSource();
source.setUrl(url);
source.setUsername(user);
source.setPassword(password);
source.setDriverClassName("com.mysql.jdbc.Driver");
source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");
```
Tomcat JDBC 데이터 소스 라이브러리는 Java용 X-Ray SDK에 포함되지만, 사용하는 문서에 제공된 종속성으로 이 라이브러리를 선언할 수 있습니다.
**Example `pom.xml` - JDBC 데이터 소스**
```
org.apache.tomcat
tomcat-jdbc
8.0.36
provided
```
## 네이티브 SQL 트레이싱 데코레이터
+ [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)을 종속성에 추가합니다.
+ 데이터베이스 데이터 소스, 연결 또는 명령문을 꾸며보세요.
```
dataSource = TracingDataSource.decorate(dataSource)
connection = TracingConnection.decorate(connection)
statement = TracingStatement.decorateStatement(statement)
preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql)
callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql)
```
# Java용 X-Ray SDK를 사용하여 사용자 지정 하위 세그먼트 생성하기
**참고**
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();
}
```
# Java용 X-Ray SDK로 세그먼트에 주석 및 메타데이터 추가하기
**참고**
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)을 참조하세요.
주석 및 메타데이터와 함께 요청, 환경 또는 애플리케이션에 대한 추가 정보를 기록할 수 있습니다. X-Ray SDK에서 생성하는 세그먼트 또는 사용자가 생성하는 사용자 지정 하위 세그먼트에 주석 및 메타데이터를 추가할 수 있습니다.
**주석**은 문자열, 숫자 또는 부울 값과 결합한 키-값 페어입니다. 주석은 [필터 표현식](xray-console-filters.md)에서 사용하기 위해 인덱싱됩니다. 주석은 콘솔의 트레이스를 그룹화할 때 사용할 데이터를 기록하거나 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API를 직접 호출할 때 사용하세요.
**메타데이터**는 객체 및 목록을 포함한 모든 유형의 값을 가질 수 있는 키-값 페어지만, 필터 표현식에 사용할 수 있도록 인덱싱되지는 않습니다. 트레이스에 저장하고 싶지만 검색에는 사용하지 않을 추가 데이터는 메타데이터를 사용하여 기록하십시오.
세그먼트에는 주석과 메타데이터 외에 [사용자 ID 문자열](#xray-sdk-java-segment-userid)도 기록할 수 있습니다. 사용자 ID는 세그먼트의 별도 필드에 기록되면 검색용으로 인덱스되지 않습니다.
**Topics**
+ [Java용 X-Ray SDK로 주석 기록하기](#xray-sdk-java-segment-annotations)
+ [Java용 X-Ray SDK로 메타데이터 기록하기](#xray-sdk-java-segment-metadata)
+ [Java용 X-Ray SDK로 사용자 ID 기록하기](#xray-sdk-java-segment-userid)
## Java용 X-Ray SDK로 주석 기록하기
주석을 사용하여 검색용으로 인덱싱할 정보를 세그먼트나 하위 세그먼트에 기록하십시오.
**주석 요구 사항**
+ **키** - X-Ray 주석의 키는 최대 500자의 영숫자를 포함할 수 있습니다. 점이나 마침표(.) 이외의 공백이나 기호를 사용할 수 없습니다.
+ **값** - X-Ray 주석의 값은 최대 1,000자의 유니코드 문자를 포함할 수 있습니다.
+ **주석** 수 - 트레이스당 최대 50개의 주석을 사용할 수 있습니다.
**주석 기록 방법**
1. `AWSXRay`에서 현재 세그먼트나 하위 세그먼트의 참조를 가져오십시오.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
또는
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. 문자열 키, 부울, 숫자 또는 문자열 값으로 `putAnnotation`을 직접 호출합니다.
```
document.putAnnotation("mykey", "my value");
```
다음 예에서는 점이 포함된 문자열 키와 부울, 숫자 또는 문자열 값을 사용하여 `putAnnotation`을 직접 호출하는 방법을 보여줍니다.
```
document.putAnnotation("testkey.test", "my value");
```
SDK는 세그먼트 문서의 `annotations` 객체에 주석을 키-값 페어로 기록합니다. 같은 키로 `putAnnotation`을 두 번 직접 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.
특정 값을 포함한 주석이 있는 트레이스를 찾으려면 `annotation[key]` 키워드를 [필터 표현식](xray-console-filters.md)에 사용하십시오.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 주석 및 메타데이터**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
Segment segment = AWSXRay.getCurrentSegment();
subsegment.putMetadata("resources", "game", game);
segment.putAnnotation("gameid", game.getId());
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
## Java용 X-Ray SDK로 메타데이터 기록하기
메타데이터를 이용해 검색용으로 인덱싱하지 않아도 되는 정보를 세그먼트나 하위 세그먼트에 기록하십시오. 메타데이터 값은 문자열, 숫자, 부울 또는 JSON 객체나 어레이에 직렬화할 수 있는 모든 객체가 될 수 있습니다.
**메타데이터 기록 방법**
1. `AWSXRay`에서 현재 세그먼트나 하위 세그먼트의 참조를 가져오십시오.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
또는
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. 문자열 네임스페이스, 문자열 키 및 부울, 숫자, 문자열 또는 객체 값으로 `putMetadata`를 호출합니다.
```
document.putMetadata("my namespace", "my key", "my value");
```
또는
키와 값만 이용해 `putMetadata`를 직접 호출합니다.
```
document.putMetadata("my key", "my value");
```
네임스페이스를 지정하지 않으면, SDK는 `default`를 사용합니다. 같은 키로 `putMetadata`을 두 번 직접 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 주석 및 메타데이터**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
Segment segment = AWSXRay.getCurrentSegment();
subsegment.putMetadata("resources", "game", game);
segment.putAnnotation("gameid", game.getId());
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
## Java용 X-Ray SDK로 사용자 ID 기록하기
사용자 ID를 요청 세그먼트에 기록하여 요청을 보낸 사용자를 식별합니다.
**사용자 ID 기록 방법**
1. `AWSXRay`에서 현재 세그먼트에 대한 참조를 가져옵니다.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
1. 요청을 보낸 사용자의 문자열 ID로 `setUser`를 직접 호출합니다.
```
document.setUser("U12345");
```
컨트롤러에서 `setUser`를 직접 호출하면 애플리케이션이 요청을 처리하는 순간부터 사용자 ID를 기록할 수 있습니다. 사용자 ID 설정용으로만 세그먼트를 사용한다면, 호출을 1줄로 연결할 수 있습니다.
**Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) – 사용자 ID**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
@RequestMapping(value="/{userId}", method=RequestMethod.POST)
public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException {
AWSXRay.getCurrentSegment().setUser(userId);
return moveFactory.newMove(sessionId, gameId, userId, move);
}
```
사용자 ID의 트레이스를 찾으려면, `user` 키워드를 [필터 표현식](xray-console-filters.md)에 적용하십시오.
## AWS X-Ray Java용 X-Ray SDK에 대한 지표
**참고**
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)을 참조하세요.
이 주제에서는 AWS X-Ray 네임스페이스, 지표 및 차원에 대해 설명합니다. Java용 X-Ray SDK를 사용하여 수집된 X-Ray 세그먼트에서 샘플링되지 않은 Amazon CloudWatch 지표를 게시할 수 있습니다. 이러한 지표는 세그먼트의 시작 및 종료 시간과 오류, 장애 및 스로틀된 상태 플래그에서 파생됩니다. 이러한 트레이스 지표를 사용하여 하위 세그먼트 내에서 재시도 및 종속성 문제를 표시할 수 있습니다.
CloudWatch는 지표 리포지토리입니다. 지표는 CloudWatch의 기본 개념으로 시간별로 정렬된 데이터 요소 세트를 나타냅니다. (또는 AWS 서비스) 지표 데이터 포인트를 CloudWatch에 게시하고 해당 데이터 포인트에 대한 통계를 순서가 지정된 시계열 데이터 세트로 검색합니다.
지표는 이름, 네임스페이스 및 하나 이상의 차원으로 고유하게 정의됩니다. 각 데이터 포인트에는 타임스탬프가 있으며 선택 사항으로 측정 단위가 있습니다. 통계를 요청하면 네임스페이스, 지표 이름 및 차원으로 반환된 데이터 스트림이 식별됩니다.
CloudWatch에 대한 자세한 정보는 [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/)를 참조하세요.
### X-Ray CloudWatch 지표
`ServiceMetrics/SDK` 네임스페이스에는 다음과 같은 지표가 포함됩니다.
| 지표 | 사용 가능 통계 | 설명 | 단위 |
| --- | --- | --- | --- |
| `Latency` | 평균, 최소, 최대, 개수 | 시작 시간과 종료 시간 간의 차이입니다. 평균, 최소 및 최대 항목은 모두 작업 지연 시간을 나타냅니다. 개수는 호출 수를 나타냅니다. | 밀리초 |
| `ErrorRate` | 평균, 합계 | `4xx Client Error` 상태 코드로 실패하여 오류가 발생한 요청 비율입니다. | % |
| `FaultRate` | 평균, 합계 | `5xx Server Error` 상태 코드로 실패하여 오류가 발생한 트레이스 비율입니다. | % |
| `ThrottleRate` | 평균, 합계 | `429` 상태 코드를 반환하는 스로틀된 트레이스 비율입니다. 이는 `ErrorRate` 지표의 하위 집합입니다. | % |
| `OkRate` | 평균, 합계 | `OK` 상태 코드를 발생시킨 트레이스된 요청 비율입니다. | % |
### X-Ray CloudWatch 차원
다음 표의 차원을 사용하여 X-Ray 계측 Java 애플리케이션에 대해 반환되는 지표를 구체화할 수 있습니다.
| 차원 | 설명 |
| --- | --- |
| `ServiceType` | 서비스 유형 (예: `AWS::EC2::Instance` 또는 알 수 없는 경우 `NONE`)입니다. |
| `ServiceName` | 서비스의 정식 이름입니다. |
### X-Ray CloudWatch 지표 활성화하기
계측된 Java 애플리케이션에서 트레이스 지표를 활성화하려면 다음 절차를 따릅니다.
**트레이스 지표를 구성하려면**
1. `aws-xray-recorder-sdk-metrics` 패키지를 Apache Maven 종속성으로 추가합니다. 자세한 내용은 [Java 서브모듈용 X-Ray SDK](#xray-sdk-java-submodules)를 참조하세요.
1. 전역 레코더 빌드의 일부로서 새 `MetricsSegmentListener()`를 활성화합니다.
**Example src/com/myapp/web/Startup.java**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard()
.withPlugin(new EC2Plugin())
.withPlugin(new ElasticBeanstalkPlugin())
.withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
1. CloudWatch 에이전트를 배포하여 Amazon Elastic Compute Cloud(Amazon EC2), Amazon Elastic Container Service(Amazon ECS) 또는 Amazon Elastic Kubernetes Service(Amazon EKS)를 사용하여 지표를 수집하세요:
+ Amazon EC2를 구성하려면 [CloudWatch 에이전트 설치](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html)를 참조하세요.
+ Amazon ECS를 구성하려면 [Monitor Amazon ECS containers using Container Insights](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html)를 참조하세요.
+ Amazon EKS를 구성하려면 [Amazon CloudWatch Observability EKS 추가 기능을 사용하여 CloudWatch 에이전트 설치](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html)를 참조하세요.
1. CloudWatch 에이전트와 통신하도록 SDK를 구성합니다. 기본적으로 SDK는 `127.0.0.1` 주소의 CloudWatch 에이전트와 통신합니다. 환경 변수 또는 Java 속성을 `address:port`로 설정하여 대체 주소를 구성할 수 있습니다.
**Example 환경 변수**
```
AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
```
**Example Java 속성**
```
com.amazonaws.xray.metrics.daemonAddress=address:port
```
**구성을 확인하려면**
1. 에 로그인 AWS Management Console 하고 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) CloudWatch 콘솔을 엽니다.
1. **지표** 탭을 열어 지표의 유입을 관찰합니다.
1. (선택 사항) CloudWatch 콘솔의 **로그** 탭에서 `ServiceMetricsSDK` 로그 그룹을 엽니다. 호스트 지표와 일치하는 로그 스트림을 찾고 로그 메시지를 확인합니다.
# 멀티스레드 애플리케이션에서 스레드 간 세그먼트 컨텍스트 전달
**참고**
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)을 참조하세요.
애플리케이션에서 새 스레드를 생성하는 경우 `AWSXRayRecorder`가 현재 세그먼트 또는 하위 세그먼트 [개체](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html)에 대한 참조를 유지하지 않습니다. 새 스레드에서 구성된 클라이언트를 사용하는 경우 SDK는 존재하지 않는 세그먼트에 쓰려고 하기 때문에 [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)이 발생합니다.
개발하는 동안 예외 발생을 방지하려면 대신 오류를 로그할 것을 알리는 [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)로 레코더를 구성합니다. [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy))를 사용하여 코드에서 전략을 구성하거나 [환경 변수](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) 또는 [시스템 속성](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)을 사용하여 동등한 수준의 옵션을 구성할 수 있습니다.
오류를 처리하는 하나의 방법은 스레드를 시작할 때 [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String))를 호출하고 스레드를 닫을 때 [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--)를 호출하여 새 세그먼트를 사용하는 것입니다. 이는 애플리케이션이 시작할 때 실행하는 코드와 같이 HTTP 요청에 대한 응답에서 실행하지 않는 코드를 구성하는 경우 유용합니다.
여러 스레드를 사용하여 수신 요청을 처리하는 경우 현재 세그먼트 또는 하위 세그먼트를 새 스레드에 전달하고 이를 전역 레코더에 제공할 수 있습니다. 이렇게 하면 새 스레드 내에서 레코딩된 정보가 해당 요청에 대해 레코딩된 나머지 정보와 동일한 세그먼트와 연결됩니다. 새 스레드에서 세그먼트를 사용할 수 있게 되면 `segment.run(() -> { ... })` 메서드를 사용하여 해당 세그먼트의 컨텍스트에 대한 액세스 권한이 있는 실행 가능 항목을 실행할 수 있습니다.
예제는 [작업자 스레드에서 구성된 클라이언트 사용](scorekeep-workerthreads.md) 섹션을 참조하세요.
## 비동기 프로그래밍과 함께 X-Ray 사용하기
Java용 X-Ray SDK는 [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html)를 사용하여 비동기 Java 프로그램에서 사용할 수 있습니다. SegmentContextExecutor는 실행자 인터페이스를 구현하므로, [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)의 모든 비동기 작업에 전달될 수 있습니다. 이렇게 하면 모든 비동기 작업이 해당 컨텍스트에서 올바른 세그먼트를 사용하여 실행될 수 있습니다.
**Example 예제 App.java: SegmentContextExecutor를 CompletableFuture에 전달하기**
```
DynamoDbAsyncClient client = DynamoDbAsyncClient.create();
AWSXRay.beginSegment();
// ...
client.getItem(request).thenComposeAsync(response -> {
// If we did not provide the segment context executor, this request would not be traced correctly.
return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());
```
# Spring 및 Java용 X-Ray SDK를 사용한 AOP
**참고**
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)을 참조하세요.
이 주제에서는 X-Ray SDK와 Spring 프레임워크를 사용하여 핵심 로직을 변경하지 않고 애플리케이션을 구성하는 방법을 설명합니다. 즉, 이제 원격으로 실행되는 애플리케이션을 계측하는 비침습적 방법이 있습니다 AWS.
**Spring에서 AOP를 활성화하는 방법**
1. [Spring 구성](#xray-sdk-java-aop-spring-configuration)
1. [애플리케이션에 추적 필터 추가](#xray-sdk-java-aop-filters-spring)
1. [코드에 주석 추가 또는 인터페이스 구현](#xray-sdk-java-aop-annotate-or-implement)
1. [애플리케이션에서 X-Ray 활성화](#xray-sdk-java-aop-activate-xray)
## Spring 구성하기
Maven 또는 Gradle을 사용하면 AOP를 사용해 애플리케이션을 도구화하도록 Spring을 구성할 수 있습니다.
Maven을 사용하여 애플리케이션을 빌드하는 경우 `pom.xml` 파일에서 다음 종속성을 추가합니다.
```
com.amazonaws
aws-xray-recorder-sdk-spring
2.11.0
```
Gradle의 경우 `build.gradle` 파일에 다음 종속성을 추가합니다.
```
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0'
```
## Spring Boot 구성하기
이전 섹션에서 설명한 Spring 종속성 외에도 Spring Boot를 사용하는 경우 클래스 경로에 아직 없는 경우 다음 종속성을 추가하세요.
Maven:
```
org.springframework.boot
spring-boot-starter-aop
2.5.2
```
Gradle:
```
compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2'
```
## 애플리케이션에 추적 필터 추가
`WebConfig` 클래스에 `Filter`를 추가하세요. 세그먼트 이름을 하나의 문자열로 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 생성자에 보냅니다. 추적 필터 및 수신 요청 계측 방법에 대한 자세한 내용은 [Java용 X-Ray SDK로 수신 요청 추적하기](xray-sdk-java-filters.md)을 참조하세요.
**Example src/main/java/myapp/WebConfig.java - spring**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## 자카르타 지원
Spring 6는 엔터프라이즈 에디션에 Javax 대신 [자카르타](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga)를 사용합니다. 이 새로운 네임스페이스를 지원하기 위해 X-Ray는 자체 자카르타 네임스페이스에 있는 병렬 클래스 집합을 만들었습니다.
필터 클래스의 경우 `javax`을 `jakarta`로 바꾸십시오. 세그먼트 네이밍 전략을 구성할 때는 다음 예시와 같이 네이밍 전략 클래스 이름 앞에 `jakarta`을 추가합니다:
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import jakarta.servlet.Filter;
import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy;
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep"));
}
}
```
## 코드에 주석 추가 또는 인터페이스 구현
클래스는 `@XRayEnabled` 어노테이션으로 주석을 달거나 `XRayTraced` 인터페이스를 구현해야 합니다. 이는 AOP 시스템에 X-Ray 구성을 위해 영향을 받는 클래스의 함수를 래핑하도록 지시합니다.
## 애플리케이션에서 X-Ray 활성화하기
애플리케이션에서 X-Ray 트레이싱을 활성화하려면 코드에서 다음 메서드를 재정의하여 추상 클래스 `BaseAbstractXRayInterceptor`를 확장해야 합니다.
+ `generateMetadata`—이 함수를 사용하면 현재 함수의 트레이스에 첨부된 메타데이터를 사용자 지정할 수 있습니다. 기본적으로 실행 함수의 클래스 이름은 메타데이터에 기록됩니다. 추가 정보가 필요한 경우 데이터를 더 추가할 수 있습니다.
+ `xrayEnabledClasses`—이 함수는 비어 있으며 그대로 유지해야 합니다. 이 함수는 인터셉터에게 래핑할 메서드를 지시하는 Pointcut에 대해 호스트의 역할을 합니다. `@XRayEnabled` 주석이 추가된 클래스 중 트레이스할 클래스를 지정하여 Pointcut을 정의합니다. 다음 Pointcut 문은 인터셉터에 `@XRayEnabled` 주석이 추가된 모든 컨트롤러 빈을 래핑하도록 지시합니다.
```
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
```
프로젝트에서 Spring 데이터 JPA를 사용하는 경우 `BaseAbstractXRayInterceptor` 대신 `AbstractXRayInterceptor`에서 확장하는 것을 고려하세요.
## 예제
다음 코드는 추상 클래스 `BaseAbstractXRayInterceptor`를 확장합니다.
```
@Aspect
@Component
public class XRayInspector extends BaseAbstractXRayInterceptor {
@Override
protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception {
return super.generateMetadata(proceedingJoinPoint, subsegment);
}
@Override
@Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)")
public void xrayEnabledClasses() {}
}
```
다음 코드는 X-Ray에 의해 구성될 클래스입니다.
```
@Service
@XRayEnabled
public class MyServiceImpl implements MyService {
private final MyEntityRepository myEntityRepository;
@Autowired
public MyServiceImpl(MyEntityRepository myEntityRepository) {
this.myEntityRepository = myEntityRepository;
}
@Transactional(readOnly = true)
public List getMyEntities(){
try(Stream entityStream = this.myEntityRepository.streamAll()){
return entityStream.sorted().collect(Collectors.toList());
}
}
}
```
애플리케이션을 올바로 구성했다면 다음 콘솔 스크린샷과 같이 컨트롤러에서 서비스 호출에 이르기까지 애플리케이션의 전체 호출 스택이 보일 것입니다.
![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/aop-spring-console.png)