SDK자바용 X-Ray 설정하기

SDKJava용 X-Ray에는 글로벌 레코더를 AWSXRay 제공하는 클래스가 포함되어 있습니다. 이는 코드를 구성하는 데 사용할 수 있는 TracingHandler입니다. 수신 HTTP 통화에 대한 세그먼트를 생성하는 AWSXRayServletFilter 것을 사용자 정의하도록 글로벌 레코더를 구성할 수 있습니다.

서비스 플러그인

plugins을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.

플러그인을 사용하려면 AWSXRayRecorderBuilder에서 withPlugin을 호출하십시오.

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

    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.

샘플링 규칙

는 X-Ray 콘솔에서 정의한 샘플링 규칙을 SDK 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. X-Ray 콘솔에서 추가 규칙을 생성하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.

는 정의된 순서대로 사용자 지정 규칙을 SDK 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 는 첫 번째 규칙만 SDK 적용합니다.

문서에서 샘플링 규칙을 SDK 로드하도록 를 구성할 수도 있습니다JSON. 는 X-Ray 샘플링을 사용할 SDK 수 없는 경우 로컬 규칙을 백업으로 사용하거나 로컬 규칙만 사용할 수 있습니다.

{
  "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를 사용하여 전역 레코더를 구성합니다.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@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를 확장하는 리스너를 추가하고 이 리스너를 배포 설명자에 등록합니다.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

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) { }
}

...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

로컬 규칙만 사용하려면 CentralizedSamplingStrategy를 LocalizedSamplingStrategy로 바꿉니다.

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

로깅

기본적으로 애플리케이션 로그에 ERROR -레벨 메시지를 SDK 출력합니다. 에서 디버그 수준 로깅을 SDK 활성화하여 애플리케이션 로그 파일에 더 자세한 로그를 출력할 수 있습니다. 유효한 로그 수준은DEBUG,, INFO WARNERROR, 및 입니다. FATAL FATAL로그 수준은 치명적 수준으로 기록되지 SDK 않기 때문에 모든 로그 메시지를 무음으로 설정합니다.

logging.level.com.amazonaws.xray = DEBUG

디버그 로그를 사용하여 수동으로 하위 세그먼트를 생성할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.

로그에 추적 ID 주입

현재의 정규화된 추적 ID를 로그 문에 노출하려면 매핑된 진단 컨텍스트에 ID를 삽입할 수 있습니다 (). MDC 메서드는 SegmentListener 인터페이스를 사용하여 세그먼트 수명 주기 이벤트 중에 X-Ray 레코더에서 호출됩니다. 세그먼트나 하위 세그먼트가 시작되면 적격 추적 ID가 키와 함께 삽입됩니다. MDC AWS-XRAY-TRACE-ID 해당 세그먼트가 끝나면 키가 에서 제거됩니다. MDC 이렇게 하면 사용 중인 로깅 라이브러리에 트레이스 ID가 표시됩니다. 하위 세그먼트가 종료되면 상위 ID가 에 삽입됩니다. MDC

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

이 기능은 SDK Java용 AWS X-Ray로 계측된 Java 애플리케이션에서 작동하며 다음과 같은 로깅 구성을 지원합니다.

각 프런트 엔드와 각 백엔드의 요구 사항은 다음 탭을 참조하십시오.

트레이스 ID 주입 예제

다음은 트레이스 ID를 포함하도록 수정된 PatternLayout 문자열을 보여줍니다. 트레이스 ID는 스레드 이름(%t) 뒤에 및 로그 레벨(%-5p) 앞에 인쇄됩니다.

%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray 쉽게 파싱할 수 있도록 로그문에 키와 트레이스 ID를 자동으로 인쇄합니다. 다음은 수정된 PatternLayout을 사용하는 로그 문을 보여줍니다.

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 세그먼트 리스너 이벤트 함수는 를 사용하여 모든 하위 세그먼트에 동일한 주석을 추가하거나, 각 세그먼트가 데몬으로 전송된 후 메시지를 기록하거나 onBeginSubsegment, 하위 세그먼트가 쿼리를 나타내는지 확인하기 위해 SQL 인터셉터가 보낸 쿼리를 기록하고 afterEndSegment, 그럴 경우 메타데이터를 beforeEndSubsegment추가하는 방식으로 구현할 수 있습니다. SQL

전체 SegmentListener 함수 목록을 보려면 Java용 Recorder 설명서를 참조하십시오.AWS X-Ray SDK API

다음 예제에서는 onBeginSubsegment를 사용하여 생성할 때 모든 하위 세그먼트에 일관된 주석을 추가하고 afterEndSegment를 사용하여 각 세그먼트의 끝에 로그 메시지를 인쇄하는 방법을 보여줍니다.

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를 빌드할 때 참조됩니다.

AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

환경 변수

환경 변수를 사용하여 SDK Java용 X-Ray를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.

환경 변수는 코드에 설정된 동등한 시스템 속성 및 값을 재정의합니다.

시스템 속성

환경 변수 대신 시스템 속성을 JVM 특정 대안으로 사용할 수 있습니다. 는 다음과 같은 속성을 SDK 지원합니다.

시스템 속성과 환경 변수가 모두 설정될 경우 환경 변수 값이 사용됩니다. 어느 방법도 코드에 설정된 값을 재정의합니다.