서비스 플러그인 샘플링 규칙 로깅 세그먼트 리스너 환경 변수 시스템 속성

SDK자바용 X-Ray 설정하기

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

Sections

서비스 플러그인
샘플링 규칙
로깅
세그먼트 리스너
환경 변수
시스템 속성

서비스 플러그인

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

플러그인

Amazon EC2 — 인스턴스 ID, 가용 영역 및 CloudWatch 로그 그룹을 EC2Plugin 추가합니다.
Elastic Beanstalk – ElasticBeanstalkPlugin이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
Amazon ECS — 컨테이너 ID를 ECSPlugin 추가합니다.
Amazon EKS — 컨테이너 ID, 클러스터 이름, 포드 ID 및 CloudWatch 로그 그룹을 EKSPlugin 추가합니다.

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

예 src/main/java/scorekeep/ .java WebConfig - 레코더


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 적용합니다.

참고

샘플링 규칙을 가져오기 위해 X-Ray에 연결할 SDK 수 없는 경우 1초마다 첫 번째 요청의 기본 로컬 규칙으로 되돌아가고 호스트당 추가 요청의 5% 로 되돌아갑니다. 이는 호스트가 샘플링을 APIs 호출할 권한이 없거나 에서 걸려온 호출에 대한 TCP API 프록시 역할을 하는 X-Ray 데몬에 연결할 수 없는 경우에 발생할 수 있습니다. SDK

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

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

예 WebConfigsrc/main/java/myapp/.java - 레코더 구성


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

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

예 WEB- /web.xml INF


...
  <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 속성을 사용하여 로깅 수준을 설정합니다.


logging.level.com.amazonaws.xray = DEBUG

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

로그에 추적 ID 주입

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

예 정규화된 트레이스 ID

정규화된 ID는 TraceID@EntityID로 표시됩니다.


1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

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

SLF4JLogback 백엔드가 있는 프런트엔드 API
SLF4JLog4J2 백엔드를 사용하는 프론트엔드 API
APILog4J2 백엔드를 사용하는 Log4J2 프론트엔드

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

SLF4J Frontend

다음 Maven 종속성을 프로젝트에 추가합니다.


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

AWSXRayRecorder를 구축할 때 withSegmentListener 메서드를 포함시킵니다. 그러면 SegmentListener 클래스가 추가되어 새 트레이스가 자동으로 삽입됩니다. IDs SLF4J MDC

SegmentListener는 선택적 문자열을 파라미터로 사용하여 log 문 접두사를 구성합니다. 접두사는 다음과 같은 방법으로 구성할 수 있습니다.
- 없음 – 기본 AWS-XRAY-TRACE-ID 접두사를 사용합니다.
- 비어 있음 – 빈 문자열(예: "")을 사용합니다.
- 사용자 지정 – 문자열에 정의된 사용자 지정 접두사를 사용합니다.
예 AWSXRayRecorderBuilder 명령문
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
```

Log4J2 front end

다음 Maven 종속성을 프로젝트에 추가합니다.


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

AWSXRayRecorder를 구축할 때 withSegmentListener 메서드를 포함시킵니다. 그러면 SegmentListener 클래스가 추가되고, 클래스는 정규화된 새 트레이스를 IDs 에 자동으로 주입합니다. SLF4J MDC

SegmentListener는 선택적 문자열을 파라미터로 사용하여 log 문 접두사를 구성합니다. 접두사는 다음과 같은 방법으로 구성할 수 있습니다.
- 없음 – 기본 AWS-XRAY-TRACE-ID 접두사를 사용합니다.
- 비어 있음 – 빈 문자열(예: "")을 사용하고 접두사를 제거합니다.
- 사용자 지정 – 문자열에 정의된 사용자 지정 접두사를 사용합니다.
예 AWSXRayRecorderBuilder 명령문
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
```

Logback backend

트레이스 ID를 로그 이벤트에 삽입하려면 각 로깅 문의 형식을 지정하는 로거의 PatternLayout을 수정해야 합니다.

patternLayout이 구성된 위치를 찾습니다. 프로그래밍 방식으로 또는 XML 구성 파일을 통해 이 작업을 수행할 수 있습니다. 자세한 내용은 Logback 구성을 참조하십시오.
향후 로깅 명령문에 추적 ID를 patternLayout 삽입하려면 의 %X{AWS-XRAY-TRACE-ID} 아무 곳에나 삽입하십시오. %X{}에서 제공된 키를 사용하여 값을 검색하고 있음을 나타냅니다. MDC PatternLayouts 로그백에 대한 자세한 내용은 을 참조하십시오. PatternLayout

Log4J2 backend

patternLayout이 구성된 위치를 찾습니다. 프로그래밍 방식으로 또는, XML JSONYAML, 또는 속성 형식으로 작성된 구성 파일을 통해 이 작업을 수행할 수 있습니다.

구성 파일을 통해 Log4J2를 구성하는 방법에 대한 자세한 내용은 구성을 참조하십시오.

프로그래밍 방식으로 Log4J2를 구성하는 방법에 대한 자세한 내용은 프로그래밍 방식으로 구성을 참조하십시오.
향후 로깅 명령문에 추적 ID를 PatternLayout 삽입하려면 의 %X{AWS-XRAY-TRACE-ID} 아무 곳에나 삽입하십시오. %X{}에서 제공된 키를 사용하여 값을 검색하고 있음을 나타냅니다. MDC PatternLayoutsLog4J2에 대한 자세한 내용은 패턴 레이아웃을 참조하십시오.

트레이스 ID 주입 예제

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

예 ID 주입이 있는 `PatternLayout`


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

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

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

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

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

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

예 AWSXRayRecorderBuilder 성명서


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

환경 변수

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

AWS_XRAY_CONTEXT_MISSING – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 RUNTIME_ERROR로 설정합니다.
유효한 값
- RUNTIME_ERROR— 런타임 예외가 발생합니다.
- LOG_ERROR – 오류를 기록하고 계속합니다 (기본값).
- IGNORE_ERROR— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
AWS_XRAY_DAEMON_ADDRESS – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 추적 데이터 (UDP) 와 샘플링 (TCP) 127.0.0.1:2000 모두에 SDK 사용됩니다. 다른 포트에서 수신 대기하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
형식
- 동일한 포트 – address:port
- 다른 포트 – tcp:address:port udp:address:port
AWS_LOG_GROUP— 로그 그룹 이름을 애플리케이션과 관련된 로그 그룹으로 설정합니다. 로그 그룹이 애플리케이션과 동일한 AWS 계정 및 지역을 사용하는 경우, X-Ray는 이 지정된 로그 그룹을 사용하여 애플리케이션의 세그먼트 데이터를 자동으로 검색합니다. 로그 그룹에 대한 자세한 내용은 로그 그룹 및 스트림 작업을 참조하십시오.
AWS_XRAY_TRACING_NAME— 세그먼트에 사용할 서비스 이름을 설정합니다. SDK 서블릿 필터의 세그먼트 이름 지정 전략에 설정한 서비스 이름을 재정의합니다.

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

시스템 속성

환경 변수 대신 시스템 속성을 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와 동등합니다.

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

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

자동 계측 에이전트

수신 요청

SDK자바용 X-Ray 설정하기

Sections

서비스 플러그인

플러그인

예 src/main/java/scorekeep/ .java WebConfig - 레코더

샘플링 규칙

참고

예 sampling-rules.json

예 WebConfigsrc/main/java/myapp/.java - 레코더 구성

예 src/com/myapp/web/Startup.java

예 WEB- /web.xml INF

로깅

예 애플리케이션 속성

로그에 추적 ID 주입

예 정규화된 트레이스 ID

예 `AWSXRayRecorderBuilder` 명령문

예 `AWSXRayRecorderBuilder` 명령문

트레이스 ID 주입 예제

예 ID 주입이 있는 `PatternLayout`

예 ID 주입이 있는 로그 문

세그먼트 리스너

예 MySegmentListener.java

예 AWSXRayRecorderBuilder 성명서

환경 변수

유효한 값

형식

시스템 속성

SDK자바용 X-Ray 설정하기

Sections

서비스 플러그인

플러그인

예 src/main/java/scorekeep/ .java WebConfig - 레코더

샘플링 규칙

참고

예 sampling-rules.json

예 WebConfigsrc/main/java/myapp/.java - 레코더 구성

예 src/com/myapp/web/Startup.java

예 WEB- /web.xml INF

로깅

예 애플리케이션 속성

로그에 추적 ID 주입

예 정규화된 트레이스 ID

예 AWSXRayRecorderBuilder 명령문

예 AWSXRayRecorderBuilder 명령문

트레이스 ID 주입 예제

예 ID 주입이 있는 PatternLayout

예 ID 주입이 있는 로그 문

세그먼트 리스너

예 MySegmentListener.java

예 AWSXRayRecorderBuilder 성명서

환경 변수

유효한 값

형식

시스템 속성

예 `AWSXRayRecorderBuilder` 명령문

예 `AWSXRayRecorderBuilder` 명령문

예 ID 주입이 있는 `PatternLayout`