Prerequisites 创建 Amazon EC2 实例安装AmazonCLI 部署 Scorekeep 生成跟踪数据获取数据配置 Amazon SNS 通知清除后续步骤

通过 Amazon CLI 开始使用 Amazon X-Ray

本教程介绍如何使用 Amazon CLI 通过 Amazon CloudFormation 模板部署 Scorekeep 示例应用程序，然后生成和检索跟踪数据。您可以使用Amazon CLI直接访问 X-Ray 服务，以及使用与 X-Ray 控制台检索服务图和原始跟踪数据时所用的相同 API。

要访问原始服务地图和追踪数据，请使用Amazon CLI调用 X-Ray API。服务地图和跟踪数据采用 JSON 格式。然后，您可以查询跟踪数据，以确保您的应用程序发送数据，也可作为测试自动化的一部分检查特定字段。

完成本教程需要大约 30 分钟。虽然我们提供链接可了解更多有关各种相关主题，则无需离开此页即可完成教程。我们建议您打开并查看脚本在文本编辑器中或GitHub 存储库当你走。这些脚本演示了 Amazon CLI 的使用案例以及如何管理由 API 调用返回的数据。

主题

Prerequisites
创建 Amazon EC2 实例
安装AmazonCLI
部署 Scorekeep
生成跟踪数据
获取数据
配置 Amazon SNS 通知
清除
后续步骤

Prerequisites

以下各节描述您应该了解的知识以及必须具有哪些权限才能访问本教程。

本教程使用 Ubuntu 服务器 18.04 LTS 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例，该实例是Amazon符合免费套餐资格。Ubuntu 实例提供了一个终端。为了遵循本教程中的步骤，您需要一个命令行终端或 Shell，以便运行命令。命令显示在列表中，前面有一个提示符号 ($)。


$ this is a command
this is output

您还应该熟悉如何在终端中使用 vi。vi 上有许多信息资源可供您学习基本命令，例如 Vim 备忘单。

在处理 Amazon EC2 实例时，获取凭证的建议方法是使用实例配置文件角色。这允许您委派权限以发出 API 请求，而无需分发您的 Amazon 凭证。您将创建一个Amazon Identity and Access Management(IAM) 角色，该角色指定您要授予 Amazon EC2 实例上运行的应用程序的权限。

使用以下步骤准备要在创建时附加到 Amazon EC2 实例的角色。

创建 Scorekeep 角色

登录到 Amazon Web Services Management Console，然后通过以下网址打开 IAM 控制台：https://console.aws.amazon.com/iam/。
选择 Role，然后选择 Create role。
UNDER常见使用案例中，选择EC2，然后选择后续：Permissions (下一步：权限)。
选择AdministratorAccess，然后选择后续：标签。
选择 Next:。审核，分配名称scorekeep-ubuntu，然后选择创建角色。

创建 Amazon EC2 实例

要演示如何使用Amazon CLI，首先通过控制台部署干净的 Amazon EC2 实例。本教程的其余部分需要此实例。

创建 Ubuntu Amazon EC2 实例

登录到 Amazon Web Services Management Console，然后通过以下网址打开 Amazon EC2 控制台：https://console.aws.amazon.com/ec2/。
验证您位于要创建实例的 Amazon 区域中。
选择 Launch Instance。使用搜索功能筛选 Ubuntu，然后选择 Ubuntu Server 18.04 LTS。它符合 Amazon 免费套餐资格。
从启动向导的顶部，选择3. 配置实例。然后，将您在权限先决条件中创建的 scorekeep-ubuntu 角色分配给 IAM 角色字段。
从启动向导的顶部，选择5. 添加标签，然后选择添加标签。接下来执行以下操作：
- 对于键，输入 Name。
- 在 Value（值）中输入 scorekeep-ubuntu。
从启动向导的顶部，选择6. 配置安全组。将安全组名称重命名为 scorekeep-ubuntu。
（可选）对于源，选择我的 IP。限制对您的实例的访问权限是一种安全最佳实践。
选择 Review and Launch，然后选择 Launch。
选择创建新密钥对并将其命名为 scorekeep-ubuntu-key。
选择下载密钥对，然后选择启动实例。

启动该实例需要不到五分钟，您可以在不久后连接。

连接到 Ubuntu Amazon EC2 实例

登录到 Amazon Web Services Management Console，然后通过以下网址打开 Amazon EC2 控制台：https://console.aws.amazon.com/ec2/。
验证您位于您创建实例的 Amazon 区域中。
选择 Instances。
在实例列表中，选择 scorekeep-ubuntu。
有关连接方法的说明，请选择连接。

安装AmazonCLI

连接到实例后，您需要安装 Amazon CLI。在后续步骤中，您可以使用 Amazon CLI 命令来创建资源，部署已分析的应用程序，以及在部署的应用程序上提取跟踪数据。

要配置 Amazon CLI 和进行调用，您需要 Amazon 访问密钥 ID 和 Amazon 秘密访问密钥。处理 Amazon EC2 实例时，请使用附加到您的实例的角色以获取这些凭证。请勿使用您的个人密钥。

有关 Amazon EC2 上的实例配置文件的详细信息和方案，请参阅适用于 Amazon EC2 的 IAM 角色和将临时凭证用于Amazonresources。

安装和配置 Amazon CLI

运行以下命令以下载 Amazon 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 框架实施 JSON Web API，以及Amazon SDK for Java将数据保存到 DynamoDB。应用程序中的 servlet 筛选条件用于分析应用程序所服务的所有传入请求。请求处理程序Amazon开发工具包客户端仪器对 DynamoDB 的下游调用。

该程序包含有多个编号的 Shell 脚本，这些脚本简化了资源的创建。该程序包还包括一个 Amazon CloudFormation 模板。了解相关更多信息Amazon CloudFormation，请参阅是什么AmazonCloudFormation？

下载和部署 Scorekeep

运行以下命令来安装和配置 git，然后运行 git clone 以将 Scorekeep 存储库克隆到 Ubuntu 服务器。Scorekeep 对于不同的入门项目有不同的分支。在本教程中，请运行 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 脚本创建一个包含 Amazon Elastic Beanstalk 环境的 Amazon CloudFormation 堆栈。它使用Amazon 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文件创建一个具有所需权限的 Elastic Beanstalk 环境、Amazon DynamoDB 表以及示例应用程序所使用的其他资源。

例 eb-java-scorekeep/template.yml


AWSTemplateFormatVersion: 2010-09-09
Description: An Amazon 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 应用程序并开始生成跟踪数据。

生成跟踪数据

在测试 API 时，您还可以使用此程序包中包含的 test-api.sh 脚本运行端到端方案并生成各种跟踪数据。

使用 test-api.sh 脚本

安装 jq 库。test-api.sh 脚本使用 jq 解析 API 调用返回的 JSON。
```
$ sudo apt install jq
```

使用 Amazon CLI 以获取环境的 CNAME。使用 EnvironmentName BETA 进行查询。这是在 Amazon 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",
			...
}

打开 /bin/test-api.sh 并使用您环境的 URL 替换 API 的值。


eb-java-scorekeep$ vi bin/test-api.sh
				
#!/bin/bash
API=scorekeep-ubuntu.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api

运行脚本以生成对 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"]}

获取数据

您可以使用 GetServiceGraph API 来检索 JSON 服务图。API 需要开始时间和结束时间。您可以使用 date 命令从 Linux 终端计算这些时间。


$ date +%s
1499394617

date +%s 显示日期 (秒数)。使用该数字作为结束时间，并从中减去一个时间可得到开始时间。

例用于检索最后 10 分钟的服务图的脚本


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

以下示例显示了一个包含四个节点的服务图形，其中包括一个客户端节点、一个客户端节点、一个客户端节点、一个表和一个 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 通知

当用户完成游戏时，记分保存使用 Amazon SNS 发送通知。当应用程序启动时，它试图为在环境变量中定义的电子邮件地址创建订阅。该调用当前失败，导致原始数据中出现 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",
    ...
}

更新完成后，Scoreep 重新启动并创建 Amazon SNS 主题的订阅。当您完成游戏时，检查电子邮件并确认订阅以查看更新。

清除

运行 6-cleanup.sh 脚本以删除您创建的存储桶并删除 Amazon CloudFormation 堆栈。系统将要求您使用 yes 或 no 进行确认。确认后，您可以退出命令行、终止 Amazon EC2 实例以及删除您的 IAM 角色。

终止 Amazon EC2 实例（控制台）

登录到 Amazon Web Services Management Console，然后通过以下网址打开 Amazon EC2 控制台：https://console.aws.amazon.com/ec2/。
验证您位于您创建实例的区域中。
选择 Instances。
在实例列表中，选择 scorekeep-ubuntu。
选择 Actions。
从列表中，选择实例状态，然后选择终止。
要确认，请选择是，终止。

删除 IAM 角色（控制台）

登录到 Amazon Web Services Management Console，然后通过以下网址打开 IAM 控制台：https://console.aws.amazon.com/iam/。
选择 Roles (角色)。搜索 scorekeep-ubuntu 并选择它。
选择删除角色，然后选择是，删除。

后续步骤

有关 X-Ray 的更多信息，Amazon X-Ray 概念。

要分析您自己的应用程序，请了解有关适用于 Java 的 X-Ray 开发工具包或其他某个 X-Ray 开发工具包的更多信息，请参阅以下内容：

要 X-Ray 本地或Amazon，请参阅Amazon X-Ray 守护程序。

要更好地了解 GitHub 上的示例应用程序，请参阅 eb-java-scorekeep。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

示例应用程序

Amazon开发工具包客户端