先决条件创建 Amazon EC2 实例安装 AWS CLI 部署 Scorekeep 生成跟踪数据获取数据配置 Amazon SNS 通知清除后续步骤

通过 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 调用返回的数据。

主题

先决条件
创建 Amazon EC2 实例
安装 AWS CLI
部署 Scorekeep
生成跟踪数据
获取数据
配置 Amazon SNS 通知
清除
后续步骤

先决条件

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

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


$ this is a command
this is output

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

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

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

创建 Scorekeep 角色

登录 AWS 管理控制台并通过以下网址打开 IAM 控制台 https://console.amazonaws.cn/iam/。
选择 Role，然后选择 Create role。
在常见使用案例下，选择 EC2，然后选择下一步: 权限。
选择 AdministratorAccess，然后选择下一步：标签。
选择下一步: 审核，分配名称 scorekeep-ubuntu，然后选择创建角色。

创建 Amazon EC2 实例

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

创建 Ubuntu Amazon EC2 实例

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

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

连接到 Ubuntu Amazon EC2 实例

登录 AWS 管理控制台并通过以下网址打开 Amazon EC2 控制台：https://console.amazonaws.cn/ec2/。
验证您位于您创建实例的 AWS 区域中。
选择 Instances。
在实例列表中，选择 scorekeep-ubuntu。
有关连接方法的说明，请选择连接。

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

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

下载和部署 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 脚本创建一个包含 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 文件创建一个 Elastic Beanstalk 环境，该环境具有所需的权限、Amazon DynamoDB 表以及示例应用程序所使用的其他资源。

例 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 应用程序并开始生成跟踪数据。

生成跟踪数据

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

使用 test-api.sh 脚本

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

使用 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",
			...
}

打开 /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

以下示例显示一个包含四个节点的服务图，其中包括一个客户端节点、一个 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 发送通知。当应用程序启动时，它试图为在环境变量中定义的电子邮件地址创建订阅。该调用当前失败，导致原始数据中出现 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 主题的订阅。当您完成游戏时，检查电子邮件并确认订阅以查看更新。

清除

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

终止您的 Amazon EC2 实例（控制台）

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

删除 IAM 角色（控制台）

登录 AWS 管理控制台并通过以下网址打开 IAM 控制台 https://console.amazonaws.cn/iam/。
选择 Roles (角色)。搜索 scorekeep-ubuntu 并选择它。
选择删除角色，然后选择是，删除。

后续步骤

在 AWS X-Ray 概念中了解有关 X-Ray 的更多信息。

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

要在本地或 AWS 上运行 X-Ray 守护程序，请参阅AWS X-Ray 守护程序。

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

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

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

示例应用程序

AWS 开发工具包客户端