Java용 AWS X-Ray 자동 계측 에이전트 - AWS X-Ray
샘플 애플리케이션시작하기구성문제 해결

Java용 AWS X-Ray 자동 계측 에이전트

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의 홈페이지에서 프로젝트에 대해 자세히 알아볼 수 있습니다. 또한 X-Ray 에이전트는 완전히 오픈 소스입니다. 소스 코드를 보거나, 기여하거나, 에이전트에 대한 문제를 제기하려면 GitHub의 해당 리포지토리를 방문하세요.

샘플 애플리케이션

eb-java-scorekeep 샘플 애플리케이션은 X-Ray 에이전트로 계측할 수 있도록 조정되었습니다. 이러한 기능은 에이전트가 수행하므로 이 브랜치에는 서블릿 필터나 레코더 구성이 포함되어 있지 않습니다. 애플리케이션을 로컬에서 실행하거나 AWS 리소스를 사용하여 실행하려면 샘플 애플리케이션의 readme 파일에 있는 단계를 따르세요. 샘플 앱을 사용하여 X-Ray 트레이스를 생성하는 방법은 샘플 앱의 튜토리얼에 나와 있습니다.

시작하기

자체 애플리케이션에서 X-Ray 자동 계측 Java 에이전트를 시작하려면 다음 절차를 따르십시오.

  1. 사용 중인 환경에서 X-Ray 대몬(daemon)을 실행합니다. 자세한 내용은 AWS X-Ray 데몬 단원을 참조하십시오.

  2. 에이전트의 최신 배포판을 다운로드하십시오. 아카이브의 압축을 풀고 파일 시스템에 해당 위치를 기록해 둡니다. 내용은 다음과 같아야 합니다.

    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

  3. 애플리케이션의 JVM 인수가 다음을 포함하도록 수정하여 에이전트를 활성화합니다. 해당하는 경우 -jar 인수 앞에 -javaagent 인수를 배치해야 합니다. JVM 인수를 수정하는 프로세스는 Java 서버를 시작하는 데 사용하는 도구와 프레임워크에 따라 다릅니다. 구체적인 지침은 사용 중인 서버 프레임워크의 설명서를 참조하세요.

    -javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

  4. 응용 프로그램 이름이 X-Ray 콘솔에 표시되는 방식을 지정하려면 AWS_XRAY_TRACING_NAME 환경 변수 또는 com.amazonaws.xray.strategy.tracingName 시스템 속성을 설정하십시오. 이름을 지정하지 않으면 기본 이름이 사용됩니다.

  5. 서버 또는 컨테이너를 다시 시작합니다. 이제 수신 요청과 해당 다운스트림 호출이 추적됩니다. 예상 결과가 표시되지 않는 경우 문제 해결을 참조하십시오.

구성

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 
}

구성 사양

다음 표에서는 각 속성의 유효한 값에 대해 설명합니다. 속성 이름은 대소문자를 구분하지만 키는 대소문자를 구분하지 않습니다. 환경 변수 및 시스템 속성으로 재정의할 수 있는 속성의 경우 우선 순위는 항상 환경 변수, 시스템 속성, 구성 파일 순입니다. 재정의할 수 있는 속성에 대한 자세한 내용은 환경 변수 단원을 참조하세요. 모든 필드는 선택 사항입니다.

속성 이름 유형 유효값 설명 환경 변수 시스템 속성 기본값

serviceName

String

모든 문자열

X-Ray 콘솔에 표시되는 계측된 서비스의 이름

AWS_XRAY_TRACING_NAME

com.amazonaws.xray.Strategy.tracingName

XRayInstrumentedService

contextMissingStrategy

String

LOG_ERROR, IGNORE_ERROR

에이전트가 X-Ray 세그먼트 컨텍스트를 사용하려고 시도했지만 아무것도 없을 때 에이전트가 취하는 작업입니다.

AWS_XRAY_CONTEXT_MISSING

com.amazonaws.xray.Strategy.Context Missing Strategy

LOG_ERROR

daemonAddress

String

포맷된 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

String

CENTRAL, LOCAL, NONE, ALL

에이전트가 사용하는 샘플링 전략. ALL은 모든 요청을 캡처하고, NONE은 요청을 캡처하지 않습니다. 샘플링 규칙을 참조하세요.

N/A

N/A

CENTRAL

traceIdInjectionPrefix

String

모든 문자열

로그에 트레이스 ID를 삽입하기 전에 제공된 접두사를 포함합니다.

N/A

N/A

없음 (빈 문자열)

samplingRulesManifest

String

절대 파일 경로

로컬 샘플링 전략에 대한 샘플링 규칙의 소스 또는 중앙 전략에 대한 대체 규칙으로 사용할 사용자 지정 샘플링 규칙 파일의 경로입니다.

N/A

N/A

DefaultSamplingRules.json

awsServiceHandlerManifest

String

절대 파일 경로

AWS SDK 클라이언트로부터 추가 정보를 캡처하는 사용자 지정 매개변수 허용 목록의 경로입니다.

N/A

N/A

DefaultOperationParameterWhitelist.json

awsSdkVersion

Integer

1, 2

사용 중인 Java용 AWS SDK 버전입니다. awsServiceHandlerManifest이 설정되지 않은 경우 무시됩니다.

N/A

N/A

2

maxStackTraceLength

Integer

음수가 아닌 정수

트레이스에 기록할 스택 트레이스의 최대 줄 수입니다.

N/A

N/A

50

streamingThreshold

정수

음수가 아닌 정수

최소한 이만큼의 서브세그먼트가 닫힌 후에는 청크가 너무 커지는 것을 방지하기 위해 아웃오브밴드 (out-of-band) 대몬(daemon)으로 스트리밍됩니다.

N/A

N/A

100

traceIdInjection

불

True, False

로깅 구성에 설명된 종속성 및 구성도 추가된 경우 로그에 X-Ray trace ID 삽입을 활성화합니다. 그렇지 않으면 아무 작업도 수행하지 않습니다.

N/A

N/A

TRUE

pluginsEnabled

불

True, False

운영 중인 AWS 환경에 대한 메타데이터를 기록하는 플러그인을 활성화합니다. 플러그인을 참조하십시오.

N/A

N/A

TRUE

collectSqlQueries

불

True, False

SQL 쿼리 문자열을 SQL 하위 세그먼트에 최선을 다해 기록합니다.

N/A

N/A

FALSE

contextPropagation

불

True, False

true인 경우 스레드 간에 X-Ray 컨텍스트를 자동으로 전파합니다. 그렇지 않으면 Thread Local을 사용하여 컨텍스트를 저장하고 스레드 간 수동 전파가 필요합니다.

N/A

N/A

TRUE

로깅 구성

X-Ray 에이전트의 로그 수준은 Java용 X-Ray SDK와 동일한 방식으로 구성할 수 있습니다. Java용 X-Ray SDK를 사용하여 로깅을 구성하는 방법에 대한 자세한 내용은 로깅를 참조하십시오.

수동 구성

에이전트의 자동 계측 외에도 수동 계측을 수행하려는 경우 프로젝트에 종속 항목으로 X-Ray SDK를 추가하세요. 수신 요청 추적에서 언급한 SDK의 사용자 지정 서블릿 필터는 X-Ray 에이전트와 호환되지 않는다는 점에 유의하십시오.

참고

에이전트를 사용하는 동시에 수동 계측을 수행하려면 최신 버전의 X-Ray SDK를 사용해야 합니다.

Maven 프로젝트에서 작업하는 경우 pom.xml 파일에 다음 종속성을 추가하세요.

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

Gradle 프로젝트에서 작업하는 경우 build.gradle 파일에 다음 종속성을 추가하세요.

implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'

에이전트를 사용하는 동안 일반 SDK와 마찬가지로 주석, 메타데이터, 사용자 ID 외에도 사용자 지정 하위 세그먼트를 추가할 수 있습니다. 에이전트는 스레드 간에 컨텍스트를 자동으로 전파하므로 멀티스레드 애플리케이션에서 작업할 때는 컨텍스트를 전파하기 위한 해결 방법이 필요하지 않습니다.

문제 해결

에이전트는 완전 자동 계측 기능을 제공하기 때문에 문제가 발생했을 때 문제의 근본 원인을 파악하기 어려울 수 있습니다. X-Ray 에이전트가 예상대로 작동하지 않는 경우 다음 문제와 해결 방법을 검토하세요. X-Ray 에이전트와 SDK는 자카르타 커먼즈 로깅 (JCL) 을 사용합니다. 로깅 출력을 보려면 다음 예제와 같이 JCL을 로깅 백엔드에 연결하는 브리지가 클래스 경로에 있는지 확인하십시오. log4j-jcl 또는 jcl-over-slf4j

문제: 애플리케이션에서 Java 에이전트를 활성화했지만 X-Ray 콘솔에 아무 것도 표시되지 않습니다.

X-Ray 대몬(daemon)이 동일한 시스템에서 실행되고 있습니까?

그렇지 않은 경우, X-Ray 대몬(daemon) 설명서를 참조하여 설정하십시오.

애플리케이션 로그에 “X-Ray 에이전트 레코더 초기화”와 같은 메시지가 표시됩니까?

에이전트를 애플리케이션에 올바르게 추가한 경우 이 메시지는 애플리케이션이 시작될 때 요청을 받기 시작하기 전에 INFO 레벨로 기록됩니다. 이 메시지가 없으면 Java 에이전트가 Java 프로세스와 함께 실행되고 있지 않은 것입니다. 모든 설정 단계를 오타 없이 올바로 따랐는지 확인하십시오.

애플리케이션 로그에 “AWS X-Ray 컨텍스트 누락 예외 표시 안 함”과 같은 오류 메시지가 여러 개 표시되나요?

이러한 오류는 에이전트가 AWS SDK 요청 또는 SQL 쿼리와 같은 다운스트림 요청을 계측하려고 하지만 에이전트가 세그먼트를 자동으로 만들지 못했기 때문에 발생합니다. 이러한 오류가 많이 발생하는 경우 에이전트가 사용 사례에 가장 적합한 도구가 아닐 수 있으므로 대신 X-Ray SDK를 사용한 수동 계측을 고려해 볼 수 있습니다. 또는 X-Ray SDK 디버그 로그를 활성화하여 컨텍스트 누락 예외가 발생한 위치의 스택 추적을 볼 수 있습니다. 코드의 이러한 부분을 사용자 지정 세그먼트로 래핑하여 이러한 오류를 해결할 수 있습니다. 다운스트림 요청을 사용자 지정 세그먼트로 래핑하는 예제는 스타트업 코드 계측의 샘플 코드를 참조하십시오.

문제: 예상했던 일부 세그먼트가 X-Ray 콘솔에 표시되지 않습니다.

애플리케이션이 멀티스레딩을 사용하나요?

생성될 것으로 예상되는 일부 세그먼트가 콘솔에 표시되지 않는 경우 애플리케이션의 백그라운드 스레드가 원인일 수 있습니다. 애플리케이션이 AWS SDK로 Lambda 함수를 한 번 직접 호출하거나 일부 HTTP 엔드포인트를 주기적으로 폴링하는 등 “실행만 하면 잊어버리는” 백그라운드 스레드를 사용하여 작업을 수행하는 경우, 스레드 간에 컨텍스트를 전파하는 동안 에이전트가 혼란을 야기할 수 있습니다. 이것이 문제인지 확인하려면 X-Ray SDK 디버그 로그를 활성화하고 진행 중인 하위 세그먼트의 상위 세그먼트로 이름이 지정된 세그먼트를 내보내지 않음과 <NAME >과 같은 메시지가 있는지 확인하세요. 이 문제를 해결하려면 서버가 돌아오기 전에 백그라운드 스레드를 결합하여 해당 스레드에서 수행한 모든 작업이 기록되도록 할 수 있습니다. 또는 백그라운드 스레드에서 컨텍스트 전파를 비활성화하도록 에이전트의 contextPropagation 구성을 false로 설정할 수 있습니다. 이렇게 하면 사용자 지정 세그먼트를 사용하여 해당 스레드를 수동으로 계측하거나 해당 스레드에서 발생하는 컨텍스트 누락 예외를 무시해야 합니다.

샘플링 규칙을 설정하셨나요?

X-Ray 콘솔에 무작위로 또는 예상치 못한 세그먼트가 표시되거나 콘솔에 표시될 것으로 예상한 세그먼트가 표시되지 않는 경우 샘플링 문제가 발생한 것일 수 있습니다. X-Ray 에이전트는 X-Ray 콘솔의 규칙을 사용하여 생성하는 모든 세그먼트에 중앙 집중식 샘플링을 적용합니다. 기본 규칙은 초당 1개의 세그먼트이며 이후 세그먼트의 5% 가 샘플링됩니다. 즉, 에이전트를 사용하여 빠르게 생성된 세그먼트는 샘플링되지 않을 수 있습니다. 이 문제를 해결하려면 X-Ray 콘솔에서 원하는 세그먼트를 적절히 샘플링하는 사용자 지정 샘플링 규칙을 만들어야 합니다. 자세한 내용은 샘플링을 참조하십시오.