翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
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 デーモンを実行するリソースを作成および設定します。チュートリアルでインストールと実行をする前提条件として以下が必要です。
-
アクセス許可が限定された IAM ユーザーを使用する場合は、IAM コンソール
に次のユーザーポリシーを追加してください。 -
AWSCloudFormationFullAccess– にアクセスして使用する CloudFormation -
AmazonS3FullAccess— を使用してテンプレートファイルを CloudFormation にアップロードする AWS Management Console -
IAMFullAccess– Amazon ECS インスタンスロールと Amazon EC2 インスタンスロールを作成 -
AmazonEC2FullAccess– Amazon EC2 リソースを作成 -
AmazonDynamoDBFullAccess– DynamoDB テーブルを作成 -
AmazonECS_FullAccess– Amazon ECS リソースを作成 -
AmazonSNSFullAccess– Amazon SNS トピックを作成 -
AWSXrayReadOnlyAccess- X-Ray コンソールでトレースマップとトレースを表示するアクセス許可用
-
-
を使用してチュートリアルを実行するには AWS CLI、 CLI バージョン 2.7.9 以降をインストールし、前のステップの ユーザーを使用して CLI を設定します。ユーザー AWS CLI で を設定するときは、リージョンが設定されていることを確認してください。リージョンが設定されていない場合は、すべての CLI コマンドに
--regionを追加する必要があります。AWS-REGION -
サンプルアプリケーションリポジトリを複製ために、Git
がインストールされていることを確認してください。 -
次のコード例を使用して、Scorekeep リポジトリの
xray-gettingstartedブランチのクローンを作成します。git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted
を使用して Scorekeep アプリケーションをインストールする CloudFormation
トレースデータの生成
サンプルアプリケーションには、フロントエンドのウェブアプリケーションが含まれています。ウェブアプリケーションを使用して API へのトラフィックを生成し、トレースデータを X-Ray に送信します。まず、 AWS Management Console または AWS CLIを使用してウェブアプリの URL を取得します。
ウェブアプリケーションを使用してトレースデータを生成する
-
[Create] を選択して、ユーザーとセッションを作成します。
-
[game name] を入力し、[Rules] を [Tic Tac Toe] に設定したら、[Create] を選択して、ゲームを作成します。
-
[Play] を選択してゲームを開始します。
-
ゲームの状態を移行および変更するには、タイルを選択します。
これらの各ステップで、API への HTTP リクエスト、および DynamoDB へのダウンストリーム呼び出しが生成され、ユーザー、セッション、ゲーム、移動、および状態データが読み書きされます。
でトレースマップを表示する AWS Management Console
サンプルアプリケーションによって生成されたトレースマップとトレースは、X-Ray および CloudWatch コンソールで確認できます。
![エラー状態のアイコンを選択して、Amazon SNS サブセグメントの [例外] ページを開きます。](images/scorekeep-gettingstarted-timeline-sns-ecs.png)
![キャプチャされた例外と記録されたスタックトレースを示す [例外] タブ](images/scorekeep-gettingstarted-exception.png)
![Amazon SNS サブセグメントの [例外] タブを表示](images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png)
この原因は、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 を追加します。
例 src/main/java/scorekeep/WebConfig.java - サーブレットフィルター
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 を使用して Gradle Docker イメージ経由で構築する
docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build例 Dockerファイル ENTRYPOINT
ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]SDK サブモジュールを依存関係として宣言することで、コンパイル中に build.gradle ファイルによって SDK サブモジュールが Maven からダウンロードされます。
例 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")
...
}
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 デーモンのトピックを参照してください。
例 ECS タスク定義内の 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 クラスの静的ブロックが含まれています。
例 src/main/java/scorekeep/WebConfig.java - レコーダー
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 が受信リクエストのセグメントを記録するレートを決定します。
例 src/main/java/resources/sampling-rules.json
{
"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」を参照してください。
例 cf-resources.yaml テンプレート ECS TaskRole 定義
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 を使用します。最後に、そのポリシーをインスタンスプロファイルに適用します。
DynamoDB リソースの ARN を識別するには :
-
DynamoDB コンソール
を開きます。 -
左側のナビゲーションバーから [テーブル] を選択します。
-
scorekeep-*のいずれかを選択すると、テーブルの詳細ページが表示されます。 -
[概要] タブで [追加情報] を選択してセクションを展開し、Amazon リソースネーム (ARN) を表示します。この値をコピーします。
-
AWS_REGIONおよびAWS_ACCOUNT_IDの値を特定のリージョンとアカウント ID に置き換えて、ARN を次の IAM ポリシーに挿入します。この新しいポリシーは、すべてのアクションを許可するAmazonDynamoDBFullAccessポリシーではなく、指定されたアクションのみ許可します。{ "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query" ], "Resource": "arn:aws:dynamodb:<AWS_REGION>:<AWS_ACCOUNT_ID>:table/scorekeep-*" } ] }アプリケーションが作成するテーブルは、一貫した命名規則に従います。
scorekeep-*形式を使用して、すべての Scorekeep テーブルを指定できます。
IAM ポリシーを変更する
-
IAM コンソールから Scorekeep タスクロール (scorekeepRole)
を開きます。 -
AmazonDynamoDBFullAccessポリシーの横にあるチェックボックスを選択して [削除] を選択し、このポリシーを削除します。 -
[アクセス許可の追加]、[ポリシーのアタッチ]、[ポリシーの作成] の順に選択します。
-
[JSON] タブを選択し、上で作成したポリシーを貼り付けます。
-
ページ下部の [次へ: タグ] を選択します。
-
ページ下部の [次へ: 確認] を選択します。
-
[名前] に、ポリシーの名前を割り当てます。
-
ページの下部の [ポリシーの作成] を選択します。
-
新しく作成したポリシーを
scorekeepRoleロールにアタッチします。アタッチしたポリシーが適用されるまで数分かかることがあります。
新しいポリシーをscorekeepRoleロールにアタッチした場合は、 CloudFormation スタックを削除する前にデタッチする必要があります。このアタッチされたポリシーにより、スタックの削除がブロックされるためです。ポリシーを削除すると、ポリシーを自動的にデタッチできます。
カスタム IAM ポリシーを削除する
-
[IAM コンソール]
を開きます。 -
左側のナビゲーションバーから [ポリシー] を選択します。
-
このセクションで先ほど作成したカスタムポリシー名を検索し、ポリシー名の横にあるラジオボタンを選択して強調表示します。
-
[アクション] ドロップダウンを選択してから、[削除] を選択します。
-
カスタムポリシーの名前を入力して [削除] を選択し、削除を確定します。これにより、ポリシーが
scorekeepRoleロールから自動的にデタッチされます。
クリーンアップ
Scorekeep アプリケーションのリソースを削除するには、次の手順を従います。
注記
このチュートリアルの前のセクションを使用してカスタムポリシーを作成してアタッチした場合は、 CloudFormation スタックを削除するscorekeepRole前に からポリシーを削除する必要があります。
次のステップ
次の章「AWS X-Ray の概念」で X-Ray の詳細をご覧ください。。
独自のアプリケーションを測定するには、X-Ray SDK for Javaまたは他の X-Ray SDK のいずれかの詳細をご覧ください。
-
X-Ray SDK for Java – AWS X-Ray SDK for Java
-
X-Ray SDK for Node.js – AWS Node.js SDK用 X-Ray
-
X-Ray SDK for .NET – AWS X-Ray SDK for .NET
X-Ray デーモンをローカルまたは で実行するには AWS、「」を参照してくださいAWS X-Ray デーモン。
でサンプルアプリケーションに寄稿するには GitHub、「」を参照してくださいeb-java-scorekeep
