AWS X-Ray SDK자바용 - AWS X-Ray
하위 모듈요구 사항종속성 관리모니터링

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

AWS X-Ray SDK자바용

SDKJava용 X-Ray는 추적 데이터를 생성하고 X-Ray 데몬으로 전송하기 위한 클래스와 메서드를 제공하는 Java 웹 애플리케이션용 라이브러리 세트입니다. 추적 데이터에는 응용 프로그램에서 제공하는 수신 HTTP 요청 및 응용 프로그램이 AWS SDK, HTTP 클라이언트 또는 데이터베이스 커넥터를 사용하여 다운스트림 서비스에 보내는 호출에 대한 정보가 포함됩니다. SQL 또한 수동으로 세그먼트를 생성하고 디버그 정보를 주석 및 메타데이터에 추가할 수도 있습니다.

SDK자바용 X-Ray는 오픈 소스 프로젝트입니다. github.com/aws/ 에서 프로젝트를 팔로우하고 이슈와 풀 리퀘스트를 제출할 수 있습니다 GitHub. aws-xray-sdk-java

AWSXRayServletFilter를 서블릿 필터로 츄가하여 수신 요청 트레이스를 시작합니다. 서블릿 필터가 세그먼트를 생성합니다. 세그먼트가 열려 있는 동안 SDK 클라이언트의 메서드를 사용하여 세그먼트에 정보를 추가하고 하위 세그먼트를 생성하여 다운스트림 호출을 추적할 수 있습니다. SDK또한 세그먼트가 열려 있는 동안 애플리케이션에서 발생하는 예외를 자동으로 기록합니다.

릴리스 1.3부터 Spring의 측면 지향 프로그래밍 () AOP 을 사용하여 애플리케이션을 계측할 수 있습니다. 즉, 응용 프로그램 런타임에 AWS코드를 추가하지 않고도 실행 중인 응용 프로그램을 계측할 수 있습니다.

다음으로, X-Ray SDK for Java를 사용하여 빌드 구성에 SDKInstrumentor 하위 모듈을 포함하여 AWS SDK for Java 클라이언트를 계측하십시오. 인스트루먼트된 클라이언트를 사용하여 다운스트림 AWS 서비스 또는 리소스를 호출할 때마다 는 해당 호출에 대한 정보를 하위 세그먼트에 SDK 기록합니다. AWS 서비스 또한 서비스 내에서 액세스하는 리소스는 추적 맵에 다운스트림 노드로 나타나므로 개별 연결의 오류 및 제한 문제를 식별하는 데 도움이 됩니다.

모든 다운스트림 통화를 계측하지 않으려면 Instrumentor 하위 모듈을 생략하고 AWS 서비스계측할 클라이언트를 선택하면 됩니다. 서비스 클라이언트에 a를 추가하여 개별 클라이언트를 계측하십시오TracingHandler. AWS SDK

다른 X-Ray SDK for Java 서브모듈은 HTTP 웹 APIs 및 데이터베이스에 대한 다운스트림 호출을 위한 계측을 제공합니다. SQL Apache HTTP서브모듈의 SDK HTTPClient Java용 X-Ray 버전을 사용하여 아파치 클라이언트를 계측할 수 있습니다. HTTPClientBuilder HTTP SQL쿼리를 계측하려면 SDK의 인터셉터를 데이터 소스에 추가하십시오.

사용을 시작한 후 레코더 및 서브렛 필터를 구성하여 동작을 사용자 지정합니다. SDK 플러그인을 추가하여 애플리케이션을 실행하는 컴퓨팅 리소스에 대한 데이터를 기록하고, 샘플링 규칙을 정의하여 샘플링 동작을 사용자 지정하고, 애플리케이션 로그에서 더 많거나 적은 정보를 볼 수 있도록 로그 수준을 설정할 수 있습니다. SDK

요청에 대한 추가 정보와 애플리케이션이 주석 및 메타데이터에서 하는 작업을 기록합니다. 주석은 필터 표현식과 함께 사용할 수 있도록 인덱싱된 단순한 키 값 쌍이기 때문에, 특정 데이터를 포함한 트레이스를 검색할 수 있습니다. 메타데이터 항목은 덜 제한적이며 전체 객체와 배열을 비롯하여 직렬화할 수 있는 모든 항목을 기록할 수 있습니다. JSON

주석 및 메타데이터

주석과 메타데이터는 X-Ray를 사용하여 세그먼트에 추가하는 임의의 텍스트입니다. SDK 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 메타데이터는 인덱싱되지 않지만 X-Ray 콘솔 또는 API 를 사용하여 원시 세그먼트에서 볼 수 있습니다. X-Ray에 대한 읽기 액세스가 부여된 사용자는 누구나 이 데이터를 볼 수 있습니다.

코드에 계측된 클라이언트가 많다면, 계측된 클라이언트로 만든 각 요청의 하위 세그먼트를 대량으로 보관하는 요청 세그먼트 하나를 만들 수 있습니다. 사용자 지정 하위 세그먼트의 클라이언트 호출을 래핑해 하위 세그먼트를 조직하고 그룹화할 수 있습니다. 전체 함수나 특정 코드 부분에 대한 사용자 지정 하위 세그먼트를 만들고, 상위 세그먼트에 모든 것을 적는 대신 하위 세그먼트에 메타데이터와 주석을 기록할 수 있습니다.

하위 모듈

Maven에서 SDK Java용 X-Ray를 다운로드할 수 있습니다. X-Ray SDK for Java는 버전 관리를 위한 BOM과 함께 사용 사례별로 하위 모듈로 분할되어 있습니다.

Maven 또는 Gradle을 사용하여 애플리케이션을 빌드하는 경우 SDKJava용 X-Ray를 빌드 구성에 추가하십시오.

SDK의 클래스와 메서드에 대한 참조 설명서는 Java AWS X-Ray SDK API Reference를 참조하십시오.

요구 사항

SDKJava용 X-Ray에는 자바 8 이상, 서블릿 API 3 AWS SDK, 및 잭슨이 필요합니다.

컴파일 및 런타임 시 다음 라이브러리에 SDK 따라 달라집니다.

  • AWS SDK자바 버전 1.11.398 이상의 경우

  • API서블릿 3.1.0

이러한 종속성은 SDK 의 pom.xml 파일에 선언되며 Maven 또는 Gradle을 사용하여 빌드하는 경우 자동으로 포함됩니다.

SDKJava용 X-Ray에 포함된 라이브러리를 사용하는 경우 포함된 버전을 사용해야 합니다. 예를 들어 런타임에 이미 Jackson을 사용하고 있고 해당 종속성에 대한 JAR 파일을 배포에 포함시킨 경우에는 자체 버전의 Jackson 라이브러리가 SDK JAR 포함되어 있으므로 해당 JAR 파일을 제거해야 합니다.

종속성 관리

SDK자바용 X-Ray는 Maven에서 구할 수 있습니다:

  • 그룹 – com.amazonaws

  • 아티팩트 – aws-xray-recorder-sdk-bom

  • 버전 – 2.11.0

Maven을 사용하여 애플리케이션을 빌드하는 경우 파일에 종속 SDK 항목으로 추가하십시오. pom.xml

예 pom.xml - 종속성
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
  </dependency>
</dependencies>

Gradle의 경우 파일에 컴파일 타임 SDK 종속 항목으로 를 추가하세요. build.gradle

예 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 사용 예시를 보려면 샘플 애플리케이션을 참조하십시오.

AWS X-Ray SDK자바용 X-Ray에 대한 메트릭

이 항목에서는 AWS X-Ray 네임스페이스, 지표 및 차원에 대해 설명합니다. SDKJava용 X-Ray를 사용하여 수집된 X-Ray 세그먼트에서 샘플링되지 않은 CloudWatch Amazon 지표를 게시할 수 있습니다. 이러한 지표는 세그먼트의 시작 및 종료 시간과 오류, 장애 및 스로틀된 상태 플래그에서 파생됩니다. 이러한 트레이스 지표를 사용하여 하위 세그먼트 내에서 재시도 및 종속성 문제를 표시할 수 있습니다.

CloudWatch 메트릭 리포지토리입니다. 지표는 데이터 요소의 기본 CloudWatch 개념이며 시간에 따라 정렬된 데이터 요소 집합을 나타냅니다. 지표 데이터 포인트를 에 CloudWatch 게시하거나 AWS 서비스해당 데이터 포인트에 대한 통계를 정렬된 시계열 데이터 세트로 검색합니다.

지표는 이름, 네임스페이스 및 하나 이상의 차원으로 고유하게 정의됩니다. 각 데이터 포인트에는 타임스탬프가 있으며 선택 사항으로 측정 단위가 있습니다. 통계를 요청하면 네임스페이스, 지표 이름 및 차원으로 반환된 데이터 스트림이 식별됩니다.

에 대한 CloudWatch 자세한 내용은 Amazon CloudWatch 사용 설명서를 참조하십시오.

X-Ray CloudWatch 메트릭스

ServiceMetrics/SDK 네임스페이스에 포함된 지표는 다음과 같습니다.

지표 사용 가능 통계 설명 단위

Latency

평균, 최소, 최대, 개수

시작 시간과 종료 시간 간의 차이입니다. 평균, 최소 및 최대 항목은 모두 작업 지연 시간을 나타냅니다. 개수는 호출 수를 나타냅니다.

밀리초

ErrorRate

평균, 합계

4xx Client Error 상태 코드로 실패하여 오류가 발생한 요청 비율입니다.

%

FaultRate

평균, 합계

5xx Server Error 상태 코드로 실패하여 오류가 발생한 트레이스 비율입니다.

%

ThrottleRate

평균, 합계

429 상태 코드를 반환하는 스로틀된 트레이스 비율입니다. 이는 ErrorRate 지표의 하위 집합입니다.

%

OkRate

평균, 합계

OK 상태 코드를 발생시킨 트레이스된 요청 비율입니다.

%

X선 CloudWatch 치수

다음 표의 측정기준을 사용하여 X-Ray 계측 Java 애플리케이션에 대해 반환되는 메트릭을 구체화하십시오.

측정기준 설명

ServiceType

서비스 유형 (예: AWS::EC2::Instance 또는 알 수 없는 경우 NONE)입니다.

ServiceName

서비스의 정식 이름입니다.

X-Ray CloudWatch 지표 활성화

다음 절차를 사용하여 계측 Java 애플리케이션에서 트레이스 메트릭을 활성화하십시오.

트레이스 지표를 구성하려면

  1. aws-xray-recorder-sdk-metrics패키지를 Apache Maven 종속 항목으로 추가합니다. 자세한 내용은 Java SDK 서브모듈용 X-Ray를 참조하십시오.

  2. 전역 레코더 빌드의 일부로서 새 MetricsSegmentListener()를 활성화합니다.

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

  3. Amazon Elastic Compute Cloud (AmazonEC2), Amazon Elastic Container Service (Amazon) 또는 Amazon Elastic Kubernetes Service (AmazonECS) 를 사용하여 지표를 수집하도록 CloudWatch 에이전트를 배포합니다. EKS

  4. 에이전트와 SDK 통신하도록 구성합니다. CloudWatch 기본적으로 는 해당 주소로 CloudWatch 127.0.0.1 에이전트와 SDK 통신합니다. 환경 변수 또는 Java 속성을 address:port로 설정하여 대체 주소를 구성할 수 있습니다.

    예 환경 변수
    AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
    예 Java 속성
    com.amazonaws.xray.metrics.daemonAddress=address:port
구성을 확인하려면

  1. 에서 AWS Management Console 로그인하고 CloudWatch 콘솔을 엽니다. https://console.aws.amazon.com/cloudwatch/

  2. 지표 탭을 열어 지표의 유입을 관찰합니다.

  3. (선택 사항) CloudWatch 콘솔의 로그 탭에서 ServiceMetricsSDK 로그 그룹을 엽니다. 호스트 지표와 일치하는 로그 스트림을 찾고 로그 메시지를 확인합니다.