기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 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\_XRAY\_TRACING\_NAME | com.amazonaws.xray.Strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | 문자열 | LOG\_ERROR, IGNORE\_ERROR | 에이전트가 X-Ray 세그먼트 컨텍스트를 사용하려고 시도했지만 아무것도 없을 때 에이전트가 취하는 작업입니다. | AWS\_XRAY\_CONTEXT\_MISSING | com.amazonaws.xray.Strategy.Context Missing Strategy | LOG\_ERROR |
| daemonAddress | 문자열 | 포맷된 IP 주소 및 포트 또는 TCP 및 UDP 주소 목록 | 에이전트가 X-Ray 대몬(daemon)과 통신하는 데 사용하는 주소입니다. | AWS\_XRAY\_DAEMON\_ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1:2000 |
| tracingEnabled | 부울 | True, False | 엑스레이 에이전트에 의한 계측을 활성화합니다. | AWS\_XRAY\_TRACING\_ENABLED | 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)을 참조하십시오.