Scorekeep サンプルアプリケーションの開始方法

このチュートリアルでは、Scorekeep サンプルアプリケーション の xray-gettingstartedブランチを使用します。Scorekeep サンプルアプリケーション は、 を使用して、Amazon ECS でサンプルアプリケーションと X-Ray デーモンを実行するリソース AWS CloudFormation を作成および設定します。アプリケーションは Spring フレームワークを使用して JSON ウェブ API を実装し、 AWS SDK for Java を使用してデータを Amazon DynamoDB に保持します。アプリケーションのサーブレットフィルターは、アプリケーションによって処理されるすべての受信リクエストを計測し、 AWS SDK クライアントのリクエストハンドラーは DynamoDB へのダウンストリーム呼び出しを計測します。

このチュートリアルは、 AWS Management Console または のいずれかを使用して実行できます AWS CLI。

前提条件

このチュートリアルでは AWS CloudFormation 、 を使用して、サンプルアプリケーションと X-Ray デーモンを実行するリソースを作成および設定します。チュートリアルでインストールと実行をする前提条件として以下が必要です。

を使用して Scorekeep アプリケーションをインストールする CloudFormation

トレースデータの生成

サンプルアプリケーションには、フロントエンドのウェブアプリケーションが含まれています。ウェブアプリケーションを使用して API へのトラフィックを生成し、トレースデータを X-Ray に送信します。まず、 AWS Management Console または AWS CLIを使用してウェブアプリの URL を取得します。

これらの各ステップで、API への HTTP リクエスト、および DynamoDB へのダウンストリーム呼び出しが生成され、ユーザー、セッション、ゲーム、移動、および状態データが読み書きされます。

でトレースマップを表示する AWS Management Console

サンプルアプリケーションによって生成されたトレースマップとトレースは、X-Ray および CloudWatch コンソールで確認できます。

この原因は、WebConfig クラスで行われた createSubscription の呼び出しで指定された E メールアドレスが無効であることを意味します。次のセクションで、これを修正します。

Amazon SNS 通知の設定

Scorekeep では、ユーザーがゲームを達成すると、Amazon SNS で通知が送信されます。アプリケーションが起動すると、 CloudFormation スタックパラメータで定義された E メールアドレスのサブスクリプションを作成しようとします。現在その呼び出しに失敗しています。通知を有効にするように通知 E メールを設定し、トレースマップで強調表示されている障害を解決します。

更新が完了すると、Scorekeep が再起動し、SNS トピックへのサブスクリプションが作成されます。E メールとサブスクリプションを確認して、ゲーム達成時にアップデートの有無を確認します。トレースマップを開いて、SNS への呼び出しが失敗していないことを確認します。

サンプルアプリケーションの詳細

サンプルアプリケーションは、X-Ray SDK for Java を使用するように設定された 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 はすべての AWS SDK クライアントを自動的に計測します。

アプリケーションは 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" ]

SDK サブモジュールを依存関係として宣言することで、コンパイル中に 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")
    }
}

core、 AWS SDK、および AWS SDK Instrumentor サブモジュールは、 AWS SDK で行われたダウンストリーム呼び出しを自動的に計測するために必要なすべてです。

未加工のセグメントデータを X-Ray API に中継するには、X-Ray デーモンが UDP ポート 2000 でトラフィックを受信する必要があります。そのため、アプリケーションでは、ECS で Scorekeep アプリケーションとともにサイドカーコンテナとしてデプロイされるコンテナでX-Ray デーモンを実行します。詳細については、X-Ray デーモンのトピックを参照してください。

...
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
      ...

X-Ray SDK for Java は、AWSXRay という名前のクラスを提供します。これはコードを計測するために使用する TracingHandler というグローバルレコーダーを提供します。グローバルレコーダーを設定して、受信 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 リクエストの固定ターゲット、および固定ターゲットが満たされた後の 1.0 または 100% のリクエストのレートを適用して、すべての POST リクエスト (リソース作成呼び出し) をキャッチします。

他の 3 つのカスタムルールでは、固定ターゲットなしで、セッション、ゲーム、および状態の読み取り (GET リクエスト) に 5% のレートを適用します。これにより、フロントエンドが、コンテンツが最新であることを確認するために数秒ごとに自動的に行う周期的呼び出しのトレース数を最小限に抑えることができます。他のすべてのリクエストの場合は、ファイルは、1 秒あたり 1 リクエストのデフォルトレートおよび 10% のレートを定義します。

また、サンプルアプリケーションでは、手動 SDK クライアント計測、追加サブセグメントの作成、HTTP 呼び出しの出力など、高度な機能の使用方法も説明します。詳細については、「AWS X-Ray サンプルアプリケーション」を参照してください。

オプション: 最小特権ポリシー

Scorekeep ECS コンテナは、AmazonSNSFullAccess や AmazonDynamoDBFullAccess などのフルアクセスポリシーを使用してリソースにアクセスします。フルアクセスポリシーの使用は、本稼働アプリケーションではベストプラクティスではありません。次の例では、DynamoDB IAM ポリシーを更新してアプリケーションのセキュリティを向上させます。IAM ポリシーのセキュリティのベストプラクティスの詳細については、AWS 「X-Ray の Identity and Access Management」を参照してください。

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 アプリケーションのリソースを削除するには、次の手順を従います。

次のステップ

次の章「概念」で X-Ray の詳細をご覧ください。。

独自のアプリケーションを測定するには、X-Ray SDK for Javaまたは他の X-Ray SDK のいずれかの詳細をご覧ください。

X-Ray デーモンをローカルまたは で実行するには AWS、「」を参照してくださいAWS X-Ray デーモン。

でサンプルアプリケーションに寄稿するには GitHub、「」を参照してくださいeb-java-scorekeep。