AWS CLI から AWS X-Ray の使用を開始する - AWS X-Ray

「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」

AWS CLI から AWS X-Ray の使用を開始する

このチュートリアルでは、AWS CLI を使用して、AWS CloudFormation テンプレートを使用した Scorekeep サンプルアプリケーションをデプロイし、トレースデータを生成および取得する方法について説明します。AWS CLI を使用して X-Ray サービスに直接アクセスできます。また、X-Ray コンソールで使用されているものと同じ API を使用して、サービスグラフや未加工のトレースデータを取得できます。

未加工のサービスマップやトレースデータにアクセスするには、AWS CLI を使用して X-Ray API を呼び出します。サービスマップとトレースデータは JSON 形式です。その後、トレースデータをクエリして、アプリケーションがデータを送信していることを確認したり、テスト自動化の一部として特定のフィールドをチェックしたりできます。

このチュートリアルの完了には約 30 分かかります。さまざまな関連トピックについて詳しく知るためのリンクを提供していますが、チュートリアルを完了するためにこのページを離れる必要はありません。スクリプトは、テキストエディタまたは GitHub リポジトリで開いて確認することをお勧めします。スクリプトは、AWS CLI のユースケースと、API コールによって返されるデータの管理方法を示しています。

前提条件

次のセクションでは、このチュートリアルを実行するために知っておくべきこと、およびアクセス可能にする必要がある権限について説明します。

このチュートリアルでは、Ubuntu Server 18.04 LTS の Amazon Elastic Compute Cloud (Amazon EC2) インスタンスを使用します。これは AWS 無料利用枠の対象です。Ubuntu インスタンスはターミナルを提供します。このチュートリアルの手順に従うには、コマンドを実行するコマンドラインターミナルまたはシェルが必要になります。コマンドは、プロンプト記号 ($) が付いたリストに表示されます。

$ this is a command this is output

また、ターミナルの vi の操作にも精通している必要があります。Vim Cheat Sheet など、基本的なコマンドについて学習できる vi 情報ソースはたくさんあります。

Amazon EC2 インスタンスで作業する場合、認証情報を取得するための推奨される方法は、インスタンスプロファイルロールを使用することです。これにより、AWS 認証情報を配布することなく、API リクエストを実行する権限を委任できます。Amazon EC2 インスタンスで実行されているアプリケーションに付与するアクセス許可を指定する AWS Identity and Access Management (IAM) ロールを作成します。

以下のステップを使用して、作成時に Amazon EC2 インスタンスにアタッチするロールを準備します。

Scorekeep ロールを作成するには

  1. AWS マネジメントコンソール にサインインし、IAM コンソール(https://console.aws.amazon.com/iam/)を開きます。

  2. [ロール]、[ロールの作成] の順に選択します。

  3. [一般的なユースケース] で [EC2] を選択し、[次へ: アクセス許可] を選択します。

  4. [AdministratorAccess] を選択し、[次へ: タグ] を選択します。

  5. [次へ: 確認] を選択し、名前 scorekeep-ubuntu を割り当てて、[ロールの作成] を選択します。

Amazon EC2 インスタンスの作成

AWS CLI を使用してサンプルアプリケーションを設定する方法を示すために、まずコンソールからクリーン Amazon EC2 インスタンスをデプロイします。チュートリアルの残りの部分では、このインスタンスが必要です。

Ubuntu Amazon EC2 インスタンスを作成するには

  1. AWS マネジメントコンソールにサインインをしたあと、https://console.aws.amazon.com/ec2/ にある Amazon EC2 コンソールを開きます。

  2. インスタンスを作成する AWS リージョンにいることを確認します。

  3. [インスタンスの作成] を選択します。検索機能を使用して Ubuntu でフィルタリングし、[Ubuntu サーバー 18.04 LTS] を選択します。AWS 無料利用枠の対象です。

  4. 起動ウィザードの上部から、[3.インスタンスの設定] を選択します。次に、アクセス許可の前提条件で作成した scorekeep-ubuntu ロールを [IAM ロール] フィールドに割り当てます。

  5. 起動ウィザードの上部から、[5.タグの追加] を選択してから、[タグの追加] を選択します。次に、以下の手順を実行します。

    • [キー] に「Name」と入力します。

    • [] に「scorekeep-ubuntu」と入力します。

  6. 起動ウィザードの上部から、[6.セキュリティグループの設定] を選択します。[セキュリティグループ名] を scorekeep-ubuntu に変更します。

  7. (オプション) [ソース] で [マイ IP] を選択します。インスタンスへのアクセスを制限することは、セキュリティのベストプラクティスです。

  8. [Review and launch] を選択し、次に [Launch] を選択します。

  9. [新しいキーペアの作成] を選択し、scorekeep-ubuntu-key と名前を付けます。

  10. [キーペアのダウンロード] を選択し、[インスタンスの作成] を選択します。

このインスタンスの作成には 5 分もかかりません。すぐに接続できます。

Ubuntu Amazon EC2 インスタンスに接続するには

  1. AWS マネジメントコンソールにサインインをしたあと、https://console.aws.amazon.com/ec2/ にある Amazon EC2 コンソールを開きます。

  2. インスタンスが作成された AWS リージョンにいることを確認します。

  3. [Instances] を選択します。

  4. インスタンスのリストで、[scorekeep-ubuntu] を選択します。

  5. 接続方法の手順については、[接続] を選択します。

AWS CLI のインストール

インスタンスに接続したら、AWS CLI をインストールする必要があります。以降のステップでは、AWS CLI コマンドを使用して、リソースの作成、計測済みアプリケーションのデプロイ、デプロイしたアプリケーションのトレースデータのプルを行います。

AWS CLI を設定し、コールを実行するには、AWS アクセスキー ID と AWS シークレットアクセスキーが必要です。Amazon EC2 インスタンスで作業するときは、インスタンスにアタッチされたロールを使用してこれらの認証情報を取得します。個人キーは使用しないでください。

Amazon EC2 のインスタンスプロファイルの詳細とシナリオについては、「Amazon EC2 の IAM ロール」および「AWS リソースでの一時的な認証情報の使用」を参照してください。

AWS CLI をインストールして設定するには

次のコマンドを実行して AWS CLI をダウンロードし、解凍してインストールします。

$ sudo apt update $ sudo apt install python3-pip $ pip3 install awscli --upgrade --user $ sudo apt install awscli $ aws --version aws-cli/1.18.63 Python/3.6.9 Linux/4.15.0-1065-aws botocore/1.16.13

次のコマンドを実行して、Amazon EC2 インスタンスロールから認証情報を取得し、使用する認証情報を割り当てます。

また、リージョンエンドポイント表から、入力するリージョンを選択する必要があります。これは必須です。これにより、後続のリソースが作成されるリージョンと、スクリプトが指す場所が決定されます。

$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/scorekeep-ubuntu { "Code" : "Success", "LastUpdated" : "2020-04-29T01:03:10Z", "Type" : "AWS-HMAC", "AccessKeyId" : "ASIAIOSFODNN7EXAMPLE", "SecretAccessKey" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "Token" : "TokenString", "Expiration" : "2020-04-29T07:38:23Z" } $ export AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE $ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY $ export AWS_SESSION_TOKEN=TokenString $ export AWS_DEFAULT_REGION=Region
注記

チュートリアルを終了する前に Amazon EC2 インスタンスから切断した場合は、これらのエクスポートコマンドを繰り返して、認証情報とリージョンを再確立する必要があります。

Scorekeep のデプロイ

これで、環境とアプリケーションの準備が整い、Scorekeep をデプロイできるようになりました。このサンプル Java アプリケーションは、セグメントを生成して X-Ray に送信します。

アプリケーションは Spring Framework を使用して JSON ウェブ API を実装し、AWS SDK for Java を使用して DynamoDB にデータを維持します。アプリケーションのサーブレットフィルタは、アプリケーションによって処理されるすべての受信リクエストを計測します。AWS SDK クライアントのリクエストハンドラは、DynamoDB へのダウンストリーム呼び出しを計測します。

パッケージには、リソースの作成を効率化するための番号付きのシェルスクリプトがいくつか含まれています。パッケージには AWS CloudFormation テンプレートも含まれています。AWS CloudFormation の詳細については、「AAWS CloudFormation とは」を参照してください。

Scorekeep をダウンロードしてデプロイするには

次のコマンドを実行して git をインストールおよび設定し、git clone を実行して Scorekeep リポジトリを Ubuntu サーバーに複製します。Scorekeep には、getting-started プロジェクトごとに異なるブランチがあります。このチュートリアルでは、git checkout xray-gettingstarted を使用します。

$ git config --global user.name "Name" $ git config --global user.email "email@domain.com" $ git clone https://github.com/aws-samples/eb-java-scorekeep.git $ cd eb-java-scorekeep eb-java-scorekeep$ git checkout xray-gettingstarted

プロジェクトのデプロイスクリプトを実行して、Amazon S3 バケットを作成し、アプリケーションをデプロイします。プロジェクトがデプロイされている間、スクリプトについて読み進めます。

eb-java-scorekeep$ ./1-create-bucket.sh make_bucket: beanstalk-artifacts-8174xmplbb388b50 eb-java-scorekeep$ ./2-deploy.sh Successfully packaged artifacts and wrote output template to file out.yml. Execute the following command to deploy the packaged template aws cloudformation deploy --template-file /home/ubuntu/eb-java-scorekeep/out.yml --stack-name scorekeep Waiting for changeset to be created.. Waiting for stack create/update to complete Successfully created/updated stack - scorekeep

1-create-bucket.sh スクリプトは、命名規則 beanstalk-artifacts-$BUCKET_ID を使用してバケットを作成します。ここで、$BUCKET_ID はランダムに生成された ID です。

2-deploy.sh スクリプトは、AWS Elastic Beanstalk 環境を含む AWS CloudFormation スタックを作成します。これは AWS CLI を使用してソースコードを Amazon S3 にアップロードし、スタックのリソースを定義するテンプレートをデプロイします。

注記

すべてのスタックアーティファクトの作成には約 10 分かかります。場合によっては、Enter キーを押して、最終的な成功メッセージを表示します。

eb-java-scorekeep/2-deploy.sh

#!/bin/bash set -eo pipefail ARTIFACT_BUCKET=$(cat bucket-name.txt) git archive --format=zip HEAD > package.zip aws cloudformation package --template-file template.yml --s3-bucket $ARTIFACT_BUCKET --output-template-file out.yml aws cloudformation deploy --template-file out.yml --stack-name scorekeep --capabilities CAPABILITY_NAMED_IAM

template.yml ファイルは、必要なアクセス許可、Amazon DynamoDB テーブル、その他サンプルアプリケーションが使用するリソースを備えた Elastic Beanstalk 環境を作成します。

eb-java-scorekeep/template.yml

AWSTemplateFormatVersion: 2010-09-09 Description: An AWS Elastic application that uses DynamoDB. Parameters: emailAddress: Type: String Default: UPDATEME Resources: application: Type: AWS::ElasticBeanstalk::Application Properties: ApplicationName: Scorekeep Description: RESTful web API in Java with Spring that provides an HTTP interface for creating and managing game sessions and users. version: Type: AWS::ElasticBeanstalk::ApplicationVersion Properties: ApplicationName: !Ref application SourceBundle: ./package.zip environment: Type: AWS::ElasticBeanstalk::Environment Properties: ApplicationName: !Ref application EnvironmentName: BETA OptionSettings: - Namespace: aws:elasticbeanstalk:application:environment OptionName: AWS_REGION Value: !Ref AWS::Region ...

デプロイが完了したら、3-open-website.sh を実行してサイト URL を取得します。

eb-java-scorekeep$ ./3-open-website.sh http://awseb-e-b-AWSEBLoa-SR79XMPLF2H8-586716793.us-west-2.elb.amazonaws.com

ブラウザでウェブサイトを開き、Web アプリを表示して、トレースデータの生成を開始します。

トレースデータの生成

パッケージに含まれる test-api.sh スクリプトを使用して、エンドツーエンドのシナリオを実行し、API をテストしながら多様なトレースデータを生成することもできます。

test-api.sh スクリプトを使用するには

  1. jq ライブラリをインストールします。test-api.sh スクリプトは、jq を使用して API コールによって返された JSON を解析します。

    $ sudo apt install jq
  2. AWS CLI を使用して、環境の CNAME を取得します。EnvironmentName BETA を使用してクエリを実行します。これは、AWS CloudFormation テンプレートで定義されている名前です。

    $ aws elasticbeanstalk describe-environments --environment-names BETA { "Environments": [ { "EnvironmentName": "BETA", "EnvironmentId": "e-fn2pvynnue", "ApplicationName": "Scorekeep", "VersionLabel": "scorekeep-version-1jd6hjta4qjzl", "SolutionStackName": "64bit Amazon Linux 2018.03 v2.10.4 running Java 8", "PlatformArn": "arn:aws:elasticbeanstalk:us-west-2::platform/Java 8 running on 64bit Amazon Linux/2.10.4", "EndpointURL": "awseb-e-f-AWSEBLoa-1UJJGXA6MKWMN-1234567.us-west-2.elb.amazonaws.com", "CNAME": "BETA.eba-example.us-west-2.elasticbeanstalk.com", ... }
  3. /bin/test-api.sh を開いて API の値を環境の URL に置き換えます。

    eb-java-scorekeep$ vi bin/test-api.sh #!/bin/bash API=scorekeep-ubuntu.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
  4. スクリプトを実行して API へのトラフィックを生成します。

    eb-java-scorekeep$ ./bin/test-api.sh Creating users, session, game, configuring game, playing game, ending game, game complete. {"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}

データの取得

JSON サービスグラフを取得するには、GetServiceGraph API を使用することができます。API には、開始時刻と終了時刻が必要です。date コマンドを使用すると、Linux ターミナルからこれらを計算できます。

$ date +%s 1499394617

date +%s は、日付を秒単位で出力します。この数字を終了時刻として使用し、ここから時間を引いて、開始時刻を作成します。

例 直近 10 分間のサービスグラフを取得するスクリプト

$ EPOCH=$(date +%s) $ aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH

次の例では、4 つのノードを持つサービスグラフを示します。これには、クライアントノード、EC2 インスタンス、DynamoDB テーブル、および Amazon Simple Notification Service (Amazon SNS) トピックが含まれます。

例 GetServiceGraph 出力

{ "Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Type": "client", "State": "unknown", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 2, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "Aliases": [] } ] }, { "ReferenceId": 1, "Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA", "Names": [ "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA" ], "Type": "AWS::DynamoDB::Table", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "DurationHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ] }, { "ReferenceId": 2, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Root": true, "Type": "AWS::EC2::Instance", "State": "active", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 1, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "Aliases": [] }, { "ReferenceId": 3, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "Aliases": [] } ], "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "DurationHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ] }, { "ReferenceId": 3, "Name": "SNS", "Names": [ "SNS" ], "Type": "AWS::SNS", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "DurationHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ] } ] }

Amazon SNS 通知の設定

Scorekeep では、ユーザーがゲームを達成すると、Amazon SNS で通知が送信されます。アプリケーション起動時、環境変数で定義された E メールアドレスのサブスクリプションが作成されます。この呼び出しが失敗したことで、raw データの ErrorStatistics カウントが発生します。

コンソールでの表示の詳細については、「X-Ray コンソールでサービスマップを表示」を参照してください。

次のコマンドは、BETA 環境の NOTIFICATION_EMAIL 変数の値を email@domain.com に設定します。

$ aws elasticbeanstalk update-environment --environment-name BETA --option-settings Namespace=aws:elasticbeanstalk:application:environment,OptionName=NOTIFICATION_EMAIL,Value=email@domain.com { "EnvironmentName": "BETA", "EnvironmentId": "e-iarzmpigxz", "ApplicationName": "Scorekeep", "VersionLabel": "scorekeep-version-1rrbj5e9c31yc", "SolutionStackName": "64bit Amazon Linux 2018.03 v2.10.7 running Java 8", ... }

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

クリーンアップ

6-cleanup.sh スクリプトを実行して、作成したバケットを削除し、AWS CloudFormation スタックを停止します。yes または no で確認を求められます。確認したら、コマンドラインを終了し、Amazon EC2 インスタンスを終了して、IAM ロールを削除できます。

Amazon EC2 インスタンスを終了するには (コンソール)

  1. AWS マネジメントコンソールにサインインをしたあと、https://console.aws.amazon.com/ec2/ にある Amazon EC2 コンソールを開きます。

  2. インスタンスが作成されたリージョンにいることを確認します。

  3. [Instances] を選択します。

  4. インスタンスのリストで、[scorekeep-ubuntu] を選択します。

  5. [Actions] を選択します。

  6. リストから、[インスタンスの状態] を選択して、[削除] を選択します。

  7. 確定するには、[はい、終了する] を選択します。

IAM ロールを削除するには (コンソール)

  1. AWS マネジメントコンソール にサインインし、IAM コンソール(https://console.aws.amazon.com/iam/)を開きます。

  2. [ロール] を選択します。scorekeep-ubuntu を検索し、選択します。

  3. [ロールの削除] を選択し、[はい、削除する] を選択します。

次のステップ

X-Ray の詳細については、「AWS X-Ray の概念」を参照してください。

独自のアプリケーションを計測するには、X-Ray SDK for Java または他の X-Ray SDK のいずれかの詳細を以下で確認してください。

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

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