Scorekeep 샘플 애플리케이션 시작하기

이 자습서에서는 Amazon ECS에서 샘플 애플리케이션과 X-Ray AWS CloudFormation 데몬을 실행하는 리소스를 생성하고 구성하는 데 사용하는 Scorekeep 샘플 애플리케이션의 xray-gettingstarted 브랜치를 사용합니다. 애플리케이션은 Spring 프레임워크를 사용하여 JSON 웹 API를 구현하고 Amazon DynamoDB에 데이터를 유지합니다. AWS SDK for Java 애플리케이션의 서블릿 필터는 애플리케이션이 처리하는 모든 수신 요청을 계측하고 AWS SDK 클라이언트의 요청 핸들러는 DynamoDB에 대한 다운스트림 호출을 계측합니다.

또는 를 사용하여 이 자습서를 따를 수 있습니다. AWS Management Console AWS CLI

필수 조건

이 자습서에서는 샘플 애플리케이션과 X-Ray 데몬을 실행하는 리소스를 만들고 구성하는 AWS CloudFormation 데 사용합니다. 튜토리얼을 설치하고 실행하려면 다음 사전 요구 사항이 필요합니다:

다음을 사용하여 Scorekeep 애플리케이션을 설치합니다. CloudFormation

데이터 추적 생성

애플리케이션에는 프런트 엔드 웹 앱이 포함되어 있습니다. 웹 앱을 사용하여 API 트래픽을 생성하고 트레이스 데이터를 X-Ray로 전송합니다. 먼저 AWS Management Console 또는 AWS CLI를 사용하여 웹 앱 URL을 검색합니다.

이들 각 단계에서 사용자, 세션, 게임, 동작 및 상태 데이터를 읽고 쓰기 위해 API에 대한 HTTP 요청과 DynamoDB에 대한 다운스트림 호출이 생성됩니다.

에서 트레이스 맵을 확인하세요. AWS Management Console

샘플 애플리케이션에서 생성된 트레이스 맵과 트레이스를 X-Ray 및 CloudWatch 콘솔에서 볼 수 있습니다.

원인은 WebConfig 클래스에서 이루어진 createSubscription 직접 호출에서 제공된 이메일 주소가 잘못된 것입니다. 다음 섹션에서는 이 문제를 해결하겠습니다.

Amazon SNS 알림 구성

Scorekeep은 Amazon SNS를 사용하여 사용자가 게임을 완료하면 알림을 전송합니다. 애플리케이션이 시작되면 CloudFormation 스택 매개변수에 정의된 이메일 주소에 대한 구독을 생성하려고 시도합니다. 해당 직접 호출은 현재 실패하고 있습니다. 알림을 활성화하도록 알림 이메일을 구성하고 추적 맵에 강조 표시된 장애를 해결하십시오.

업데이트가 완료되면 Scorekeep이 다시 시작하고 SNS 주제에 대한 구독을 생성합니다. 이메일을 확인하여 게임을 완료할 때 업데이트를 보기 위한 구독을 확인합니다. 추적 맵을 열어 SNS 호출이 더 이상 실패하지 않는지 확인합니다.

샘플 애플리케이션 탐색

샘플 애플리케이션은 Java용 X-Ray SDK를 사용하도록 구성된 Java용 HTTP 웹 API입니다. CloudFormation 템플릿을 사용하여 애플리케이션을 배포하면 DynamoDB 테이블, Amazon ECS 클러스터 및 ECS에서 Scorekeep을 실행하는 데 필요한 기타 서비스가 생성됩니다. 를 통해 ECS용 작업 정의 파일이 생성됩니다. CloudFormation 이 파일은 ECS 클러스터에서 작업별로 사용되는 컨테이너 이미지를 정의합니다. 이 이미지는 공식 X-Ray 공개 ECR에서 가져온 것입니다. Scorekeep API 컨테이너 이미지에는 Gradle로 컴파일된 API가 있습니다. Scorekeep 프론트엔드 컨테이너의 컨테이너 이미지는 nginx 프록시 서버를 사용하여 프론트엔드에 서비스를 제공합니다. 이 서버는 /api로 시작하는 경로에 대한 요청을 API로 라우팅합니다.

수신 HTTP 요청을 구성하기 위해 애플리케이션은 SDK가 제공하는 TracingFilter를 추가합니다.

import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
...

@Configuration
public class WebConfig {

  @Bean
  public Filter TracingFilter() {
    return new AWSXRayServletFilter("Scorekeep");
  }
...

이 필터는 애플리케이션이 처리하는 모든 수신 요청에 대해 요청 URL, 메소드, 응답 상태, 시작 시간 및 종료 시간을 포함한 트레이스 데이터를 전송합니다.

또한 애플리케이션은 AWS SDK for Java를 사용하여 DynamoDB에 대한 다운스트림 호출을 생성합니다. 이러한 호출을 계측하기 위해 애플리케이션은 단순히 AWS SDK 관련 하위 모듈을 종속성으로 사용하고, X-Ray SDK for Java는 모든 SDK 클라이언트를 자동으로 계측합니다. AWS

애플리케이션은 Docker을 사용하여 Gradle Docker Image와 함께 소스 코드를 인스턴스 내에서 빌드하고 Scorekeep API Dockerfile 파일을 사용하여 Gradle이 ENTRYPOINT에서 생성하는 실행 가능한 JAR을 실행합니다.

docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build

ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]

build.gradle 파일이 컴파일 도중 SDK 하위 모듈을 종속성으로 선언하여 Maven으로부터 이들 하위 모듈을 다운로드합니다.

...
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")
    ...
}
dependencyManagement {
    imports {
        mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67")
        mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0")
    }
}

코어, AWS SDK, SDK 인스트루멘터 서브모듈만 있으면 AWS SDK로 이루어진 다운스트림 호출을 자동으로 계측할 수 있습니다. AWS

원시 세그먼트 데이터를 X-Ray API로 전달하려면 X-Ray 대몬(daemon)이 UDP 포트 2000에서 트래픽을 수신해야 합니다. 이를 위해 애플리케이션은 컨테이너에서 X-Ray 대몬(daemon)을 실행하고, 이 컨테이너는 사이드카 컨테이너로 ECS에 Scorekeep 애플리케이션과 함께 배포됩니다. 자세한 내용은 X-Ray 대몬(daemon) 항목을 참조하세요.

...
Resources:
  ScorekeepTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties: 
      ContainerDefinitions: 
      ...
      
      - Cpu: '256'
        Essential: true
        Image: amazon/aws-xray-daemon
        MemoryReservation: '128'
        Name: xray-daemon
        PortMappings: 
          - ContainerPort: '2000'
            HostPort: '2000'
            Protocol: udp
      ...

Java용 X-Ray SDK는 코드를 계측하는 데 사용할 수 있는 TracingHandler인 전역 레코더를 제공하는 AWSXRay라는 클래스를 제공합니다. 전역 레코더를 구성하여 수신 HTTP 호출에 대해 세그먼트를 생성하는 AWSXRayServletFilter를 사용자 지정할 수 있습니다. 이 샘플은 WebConfig 클래스에 플러그인 및 샘플링 규칙을 사용하여 전역 레코더를 구성하는 정적 블록을 포함합니다.

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

@Configuration
public class WebConfig {
  ...
  
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new ECSPlugin()).withPlugin(new EC2Plugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
    ...
    
  }
}

이 예제는 빌더를 사용하여 sampling-rules.json 파일로부터 샘플링 규칙을 로드합니다. 샘플링 규칙은 SDK가 들어오는 요청의 세그먼트를 기록하는 비율에 따라 다릅니다.

{
  "version": 1,
  "rules": [
    {
      "description": "Resource creation.",
      "service_name": "*",
      "http_method": "POST",
      "url_path": "/api/*",
      "fixed_target": 1,
      "rate": 1.0
    },
    {
      "description": "Session polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/session/*",
      "fixed_target": 0,
      "rate": 0.05
    },
    {
      "description": "Game polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/game/*/*",
      "fixed_target": 0,
      "rate": 0.05
    },
    {
      "description": "State polling.",
      "service_name": "*",
      "http_method": "GET",
      "url_path": "/api/state/*/*/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

샘플링 규칙 파일은 4개의 사용자 지정 샘플링 규칙 및 기본 규칙을 정의합니다. 각 수신 요청에 대해, SDK가 사용자 지정 규칙을 정의된 순서대로 평가합니다. SDK는 요청의 메서드, 경로 및 서비스 이름과 일치하는 첫 번째 규칙을 적용합니다. Scorekeep의 경우, 첫 번째 규칙이 초당 1개 요청의 고정 타겟, 그리고 고정 타겟 충족 이후 1.0 즉, 100%의 요청 비율을 적용하여 모든 POST 요청(리소스 생성 호출)을 포착합니다.

다른 세 개의 사용자 지정 규칙은 고정 타겟 없이 5% 비율을 세션, 게임 및 상태 읽기(GET 요청)에 적용합니다. 이는 콘텐츠가 최신 상태를 유지하도록 하기 위해 프런트 엔드가 몇 초마다 자동으로 생성하는 주기적 호출에 대한 트레이스 수를 최소화합니다. 다른 모든 요청의 경우 파일이 초당 1개의 기본 요청 비율과 10% 비율을 정의합니다.

또한 샘플 애플리케이션은 수동 SDK 클라이언트 구성, 추가 하위 세그먼트 생성, 발신 HTTP 호출과 같은 고급 기능을 사용하는 방법도 보여줍니다. 자세한 설명은 AWS X-Ray 샘플 애플리케이션 섹션을 참조하세요.

선택 사항: 최소 권한 정책

Scorekeep ECS 컨테이너는 AmazonSNSFullAccess 및 AmazonDynamoDBFullAccess와 같은 전체 액세스 정책을 사용하여 리소스에 액세스합니다. 전체 액세스 정책을 사용하는 것은 프로덕션 애플리케이션의 모범 사례가 아닙니다. 다음 예제에서는 애플리케이션의 보안을 개선하기 위해 DynamoDB IAM 정책을 업데이트합니다. IAM 정책의 보안 모범 사례에 대해 자세히 알아보려면 AWS X-Ray의 ID 및 액세스 관리를 참조하십시오.

ECSTaskRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement: 
          - 
            Effect: "Allow"
            Principal: 
              Service: 
                - "ecs-tasks.amazonaws.com"
            Action: 
              - "sts:AssumeRole"
      ManagedPolicyArns:
        - "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"
        - "arn:aws:iam::aws:policy/AmazonSNSFullAccess"
        - "arn:aws:iam::aws:policy/AWSXrayFullAccess"
      RoleName: "scorekeepRole"

정책을 업데이트하려면 먼저 DynamoDB 리소스의 ARN을 식별합니다. 그런 다음 사용자 지정 IAM 정책에 ARN을 사용합니다. 마지막으로 이러한 정책을 인스턴스 프로파일에 적용합니다.

새 정책을 scorekeepRole 역할에 연결한 경우 스택을 삭제하기 전에 새 정책을 분리해야 합니다. 이렇게 연결된 정책은 CloudFormation 스택 삭제를 차단하기 때문입니다. 정책을 삭제하면 정책이 자동으로 분리될 수 있습니다.

정리

Scorekeep 애플리케이션 리소스를 삭제하려면 다음 절차를 따르세요.

다음 단계

다음 장 AWS X-Ray 개념에서 X-Ray에 대해 자세히 알아봅니다.

자체 앱을 계측하려면 Java용 X-Ray SDK 또는 다른 X-Ray SDK 중 하나에 대해 자세히 알아보십시오.

X-Ray 데몬을 로컬에서 실행하거나 실행하려면 을 AWS참조하십시오. AWS X-Ray 다이몬

의 샘플 애플리케이션에 GitHub 기여하려면 을 참조하십시오. eb-java-scorekeep