本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
Scorekeep 示例应用程序入门
本教程使用 Scorekeeep 示例应用程序的xray-gettingstarted分支，该分支用于 Amazon CloudFormation 创建和配置在 Amazon ECS 上运行示例应用程序和 X-Ray 守护程序的资源。该应用程序使用 Spring 框架来实现 JSON Web API，并使用将数据保存 Amazon SDK for Java 到 Amazon DynamoDB。应用程序中的 servlet 过滤器会检测应用程序处理的所有传入请求，而 Amazon SDK 客户端上的请求处理程序则用于监测 DynamoDB 的下游调用。
您可以使用 Amazon Web Services Management Console 或来学习本教程 Amazon CLI。
Sections
先决条件
本教程 Amazon CloudFormation 用于创建和配置运行示例应用程序和 X-Ray 守护程序的资源。安装和运行本教程需要满足以下先决条件：
-
如果您使用权限有限的 IAM 用户，请在 IAM 控制台
中添加以下用户策略： -
AWSCloudFormationFullAccess— 访问和使用 CloudFormation -
AmazonS3FullAccess— CloudFormation 使用将模板文件上传到 Amazon Web Services Management Console -
IAMFullAccess— 用于创建 Amazon ECS 和 Amazon EC2 实例角色 -
AmazonEC2FullAccess— 用于创建 Amazon EC2 资源 -
AmazonDynamoDBFullAccess- 用于创建 DynamoDB 表 -
AmazonECS_FullAccess- 用于创建 Amazon ECS 资源 -
AmazonSNSFullAccess- 用于创建 Amazon SNS 主题 -
AWSXrayReadOnlyAccess— 用于在 X-Ray 控制台中查看追踪地图和轨迹的权限
-
-
要使用完成本教程 Amazon CLI，请安装 CLI 版本 2.7.9 或更高版本，并使用上一步中的用户配置 CLI。使用用户配置时，请确保已 Amazon CLI 配置区域。如果未配置区域，则需要将
--region附加到每一个 CLI 命令。AWS-REGION -
确保已安装 Git
，以便克隆示例应用程序存储库。 -
使用以下代码示例克隆 Scorekeep 存储库的
xray-gettingstarted分支：git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted
使用以下命令安装 Scorekeeep 应用程序 CloudFormation
生成跟踪数据
示例应用程序包括一个前端 Web 应用程序。使用 Web 应用程序来生成 API 流量并将跟踪数据发送到 X-Ray。首先，使用 Amazon Web Services Management Console 或 Amazon CLI检索 Web 应用程序 URL：
使用 Web 应用程序生成跟踪数据
-
选择 Create 来创建用户和会话。
-
键入 game name，将 Rules 设置为 Tic Tac Toe，然后选择 Create 创建一个游戏。
-
选择 Play 以启动游戏。
-
选择平铺可进行移动和更改游戏状态。
上述每个步骤都会生成到 API 的 HTTP 请求，并对 DynamoDB 进行下游调用，以读取和写入用户、会话、游戏、移动和状态数据。
在中查看追踪地图 Amazon Web Services Management Console
您可以在 X-Ray 和 CloudWatch 控制台中查看示例应用程序生成的轨迹图和轨迹。
原因指出，在 WebConfig 类中，调用 createSubscription 时所提供的电子邮件地址无效。在下一节中，我们将会修复此问题。
配置 Amazon SNS 通知
当用户完成游戏时，Scorekeep 使用 Amazon SNS 发送通知。当应用程序启动时，它会尝试为 CloudFormation 堆栈参数中定义的电子邮件地址创建订阅。该调用目前会失败。配置通知电子邮件以启用通知，并解决追踪图中突出显示的故障。
更新完成后，Scorekeep 重新启动并创建对 SNS 主题的订阅。当您完成游戏时，检查电子邮件并确认订阅以查看更新。打开跟踪地图，验证对 SNS 的呼叫是否不再失败。
浏览示例应用程序
在 Java 中示例应用程序是一个 HTTP Web API，可配置为使用适用于 Java 的 X-Ray 开发工具包。当您使用 CloudFormation 模板部署应用程序时，它会创建 DynamoDB 表、Amazon ECS 集群以及在 ECS 上运行 Scorekeep 所需的其他服务。ECS 的任务定义文件是通过创建的 CloudFormation。此文件定义 ECS 集群中每项任务使用的容器映像。这些映像从官方 X-Ray 公共 ECR 中获取。Scorekeep API 容器映像具有兼容 Gradle 的 API。Scorekeeep 前端容器的容器映像充当使用 nginx 代理服务器的前端。此服务器会将传送到以 /api 开头的路径的请求路由到 API。
要检测传入 HTTP 请求，应用程序将添加开发工具包提供的 TracingFilter。
例 src/main/java/scorekeeep/ .java WebConfig-servlet 过滤器
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
...
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
...此筛选器会发送有关应用程序所处理所有传入请求的跟踪数据，包括请求 URL、方法、响应状态、开始时间和结束时间。
应用程序还会使用 Amazon SDK for Java对 DynamoDB 进行下游调用。要检测这些调用，应用程序只需将与 Amazon SDK 相关的子模块作为依赖项，适用于 Java 的 X-Ray SDK 会自动检测所有 Amazon 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例 Dockerfile ENTRYPOINT
ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]在编译期间，build.gradle 从 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")
}
}核心、 Amazon SDK 和 S Amazon DK Instrumentor 子模块就是自动检测使用 SDK 进行的任何下游调用所 Amazon 必需的。
如需将原始分段数据中断到 X-Ray API，则需要使用 X-Ray 进程守护程序侦听流量或 UDP 端口 2000。为此，应用程序让 X-Ray 进程守护程序在 ECS 上作为附加容器与 Scorekeep 应用程序一起部署的容器中运行。请参阅 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
...适用于 Java 的 X-Ray 开发工具包提供了一个名为 AWSXRay 的类，该类提供全局记录器，即您可用于检测代码的 TracingHandler。您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的 AWSXRayServletFilter。示例包括 WebConfig 类中的一个静态数据块，该数据块使用插件和示例规则配置全局记录器。
例 src/main/java/scorekeeep/ 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 的文件的采样规则。采样规则确定开发工具包记录传入请求分段的速率。
例 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
}
}采样规则文件定义了四个自定义采样规则和默认规则。对于每个传入请求，开发工具包按定义的顺序评估自定义规则。开发工具包应用与请求的方法、路径和服务名称匹配的第一个规则。对于 Scorekeep，第一个规则通过应用每秒 1 个请求的固定目标和 1.0 的速率来捕获所有 POST 请求 (资源创建调用)，或者，在满足固定目标后，捕获 100% 的请求。
另外三个自定义规则应用 5% 的速率，对于会话、游戏和状态读取无固定目标（GET 请求）。这样可以尽可能减少前端为确保内容最新而每隔几秒钟自动发出的定期调用的跟踪数。对于所有其他请求，该文件定义默认速率为每秒 1 个请求，速率为 10%。
示例应用程序还展示了如何使用高级功能，如手动开发工具包客户端检测、创建其他子分段和传出 HTTP 调用。有关更多信息，请参阅Amazon X-Ray 示例应用程序。
可选：最低权限策略
Scorekeeep ECS 容器使用 AmazonSNSFullAccess 和 AmazonDynamoDBFullAccess 等完整访问策略来访问资源。对于生产应用程序而言，使用完整访问策略并不是最佳做法。以下示例更新 DynamoDB IAM 策略以提升应用程序的安全性。要详细了解 IAM 策略中的安全最佳实践，请参阅 Amazon X-Ray 的身份和访问管理。
例 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）。复制该值。
-
将 ARN 插入到以下 IAM 策略中，将
AWS_REGION替换为具有您的具体区域和账户 ID 的AWS_ACCOUNT_ID值。此新策略仅允许执行指定的操作，而非允许执行任何操作的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 应用程序资源：
注意
如果您使用本教程的前一部分创建并附加了自定义策略，则必须先从中移除策略，scorekeepRole然后才能删除 CloudFormation 堆栈。
后续步骤
要了解有关 X-Ray 的更多信息，请参阅下一章概念。
要检测您自己的应用程序，请了解有关适用于 Java 的 X-Ray 开发工具包或其他 X-Ray 开发工具包的更多信息：
-
适用于 Java 的 X-Ray 开发工具包 - Amazon X-Ray 适用于 Java
-
适用于 Node.js 的 X-Ray 开发工具包 - Amazon 适用于 Node.js 的 X-ray SDK
-
适用于 .NET 的 X-Ray 开发工具包 - Amazon X-Ray 适用于.NET 的 SDK
要在本地或在本地运行 X-Ray 守护程序 Amazon，请参阅Amazon X-Ray 守护程序。
要为上的示例应用程序做出贡献 GitHub，请参阅eb-java-scorekeep