本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Amazon X-Ray 入门
开始使用Amazon X-Ray,在 Elastic Beanstalk 中启动一个已经存在的示例应用仪表化的以生成跟踪数据。在几分钟内,您可以启动示例应用程序,生成流量,将分段发送到 X-Ray,以及在中查看服务图和跟踪。Amazon Web Services Management Console.
本教程使用Java 应用程序示例生成分段并将其发送到 X-Ray。该应用程序使用 Spring 框架实施 JSON Web API 和Amazon SDK for Java将数据保存到 Amazon DynamoDB。应用程序中的 servlet 筛选器分析该应用程序处理的所有传入请求,而Amazon开发工具包客户端分析 DynamoDB 的下游调用。

借助适用于 Java 的 X-Ray 软件开发工具包,可以跟踪所有应用程序的主要和下游。Amazon资源通过进行两个配置更改:
-
在中,向 servlet 配置中添加适用于 Java 的 X-Ray 软件开发工具包
WebConfig
类或web.xml
文件。 -
在 Maven 或 Gradle 生成配置中,将适用于 Java 的 X-Ray 软件开发工具包作为生成依赖项。
您也可以通过使用访问原始服务地图和跟踪数据。Amazon CLI要调用 X-Ray API。服务地图和跟踪数据是 JSON,您可以进行查询以确保您的应用程序发送数据,也可作为测试自动化的一部分检查特定字段。
先决条件
本教程使用 Elastic Beanstalk 创建和配置资源,以运行示例应用程序和 X-Ray 守护程序。如果您使用具有有限权限的 IAM 用户,请添加Elastic Beanstalk 托管用户策略向您的 IAM 用户授予使用 Elastic Beanstalk 的权限,AWSXrayReadOnlyAccess
允许在 X-Ray 控制台中读取服务地图和跟踪的托管策略。
Elastic Beanstalk 目前不在亚太地区(雅加达)区域推出。ap-southeast-3. 选择其他一个Amazon区域以使用 ScoreKep 示例应用程序。
为示例应用程序创建 Elastic Beanstalk 环境。如果您以前未使用过 Elastic Beanstalk,这还将为您的应用程序创建一个服务角色和实例配置文件。要部署到的区域中必须存在一个默认 VPC,否则 Elastic Beanstalk 将无法部署示例应用程序。
要创建 Elastic Beanstalk 环境
-
使用下面的预配置链接打开 Elastic Beanstalk 管理控制台:https://console.aws.amazon.com/elasticbeanstalk/#/newApplication?applicationName=scorekeep
-
在平台部分中,设置平台到
Java
和平台分支到Corretto 8 running on 64bit Amazon Linux 2
.注意 这些区域有:
xray-gettingstarted
Scorekeep 应用程序的分支目前不支持 Corretto 11。 -
选择创建应用程序以创建一个应用程序以及运行 Corretto 8 平台的环境。
-
当您的环境准备就绪后,控制台会将您重定向到环境控制面板。
-
单击页面顶部的 URL 以打开站点。
您环境中的实例需要权限来将数据发送到 Amazon X-Ray 服务。此外,该示例应用程序使用 Amazon S3 和 DynamoDB。修改默认的 Elastic Beanstalk 实例配置文件以包含使用这些服务的权限。
向 Elastic Beanstalk 环境中添加 X-Ray、Amazon S3 和 DynamoDB 权限
-
在 IAM 控制台中打开 Elastic Beanstalk 实例配置文件:aws-elasticbeanstalk-ec2-role
。 -
选择附加策略。
-
AttachAWSXrayFullAccess、AmazonS3FullAccess、AmazonDynamoDBFullAccess, 和AmazonSNSFullAccess如果他们尚未出现,请参阅角色。
注意 完全访问权限策略不是适合一般使用的最佳做法。有关配置具有最低权限的策略以减少安全风险的说明,请参阅可选:权限最低策略.
部署到 Elastic Beanstalk 并生成跟踪数据
将示例应用程序部署到您的 Elastic Beanstalk 环境。示例应用程序使用 Elastic Beanstalk 配置文件来配置与 X-Ray 一起使用的环境,并创建它自动使用的 DynamoDB。
部署源代码
导航到管理控制台您的环境。
-
选择 Upload and Deploy。
-
上传 eb-java-scorekeep-xray-gettingstarted-v2.zip,然后选择部署.
示例应用程序包括一个前端 Web 应用程序。使用 Web 应用程序来生成 API 流量并将跟踪数据发送到 X-Ray。
生成跟踪数据
-
在环境控制面板中,单击相应的 URL 以打开 Web 应用程序。
-
选择 Create 来创建用户和会话。
-
键入 game name,将 Rules 设置为 Tic Tac Toe,然后选择 Create 创建一个游戏。
-
选择 Play 以启动游戏。
-
选择平铺可进行移动和更改游戏状态。
上述每个步骤都会生成到 API 的 HTTP 请求,并对 DynamoDB 进行下游调用,以读取和写入用户、会话、游戏、移动和状态数据。
在 X-Ray 控制台中查看服务地图
您可以在 X-Ray 控制台中查看示例应用程序生成的服务地图和跟踪。
要使用 X-Ray 控制台
-
打开服务地图页面X-Ray 控制台
. -
控制台将显示该服务的图形表示形式,这是 X-Ray 根据应用程序发送的跟踪数据生成的。
该服务地图显示 Web 应用程序客户端、在 Elastic Beanstalk 中运行的 API、DynamoDB 服务以及应用程序使用的每个 DynamoDB 表。对应用程序的每个请求 (最多为可配置的每秒最大请求数) 都受到跟踪 (因为请求到达 API),生成针对下游服务的请求,然后完成。
可以在服务图中选择任一节点,来查看对该节点生成流量的请求的跟踪。目前,Amazon SNS 节点为黄色。深入了解原因。

查找错误原因
-
选择名为的节点Amazon SNS. 此时将显示节点详细信息面板。
-
选择查看跟踪以访问 Trace 概述屏幕。
-
从 Trace list 中选择跟踪。该跟踪没有方法或 URL,因为它是在启动期间记录的,而不是对传入请求的响应。
-
选择页面底部的 Amazon SNS 区段中的错误状态图标以打开例外SNS 子区段的页面。
-
X-Ray 软件开发工具包会自动捕获由分析引发Amazon开发工具包客户端并记录堆栈跟踪。
原因指出,在 WebConfig
类中,调用 createSubscription
时所提供的电子邮件地址无效。让我们修复这一问题。
配置 Amazon SNS 通知
当用户完成游戏时,Scorekeep 使用 Amazon SNS 发送通知。当应用程序启动时,它试图为在环境变量中定义的电子邮件地址创建订阅。该调用目前失败,导致服务地图中的 Amazon SNS 节点变为红色。在环境变量中配置通知电子邮件,以启用通知并使服务地图变为绿色。
要配置 Amazon SNS 通知以保持记分
导航到管理控制台您的环境。
选择 Configuration。
-
选择 Software Configuration。
-
在 Environment Properties 下,用您的电子邮件地址替换默认值。
-
选择 Apply(应用)。
更新完成后,Scorekeep 重新启动并创建对 SNS 主题的订阅。当您完成游戏时,检查电子邮件并确认订阅以查看更新。
浏览示例应用程序
示例应用程序是 Java 中的 HTTP Web API,可配置为使用适用于 Java 的 X-Ray SDK for Java。当您将应用程序部署到 Elastic Beanstalk 时,它会创建 DynamoDB 表,编译 API 与 Gradle,并将 nginx 代理服务器配置为服务根路径中静态存在的 Web 应用程序。同时,Elastic Beanstalk 将请求路由到以开头的路径。/api
转到 API。
要分析传入 HTTP 请求,应用程序将添加开发工具包提供的 TracingFilter
。
例 src/main/java/scorekeep/WebConfig.java-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、方法、响应状态、开始时间和结束时间。
该应用程序还使用对 DynamoDB 进行下游调用Amazon SDK for Java. 为了检测这些调用,应用程序只需使用Amazon适用于 Java 的 X-Ray 软件开发工具包会自动分析所有内容。AmazonSDK 客户端。
该应用程序使用Buildfile
文件来在实例上使用构建源代码Gradle
和Procfile
文件来运行 Gradle 生成的可执行 JAR。Buildfile
和Procfile
支持是Elastic Beanstalk Java SE 平台.
例 Buildfile
build: gradle build
例 Procfile
web: java -Dserver.port=5000 -jar build/libs/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 开发工具包和 Amazon 开发工具包 Instrumentor 子模块就可以自动分析 Amazon 开发工具包进行的所有下游调用。
为了运行 X-Ray 守护程序,应用程序将使用 Elastic Beanstalk 的另一项功能,即配置文件。配置文件告知 Elastic Beanstalk 按需运行守护程序并发送其日志。
例 .ebextensions/xray.config
option_settings:
aws:elasticbeanstalk:xray:
XRayEnabled: true
files:
"/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" :
mode: "000644"
owner: root
group: root
content: |
/var/log/xray/xray.log
适用于 Java 的 X-Ray 软件开发工具包提供了AWSXRay
提供全局记录器,TracingHandler
您可以用于分析代码的。您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的 AWSXRayServletFilter
。示例包括 WebConfig
类中的一个静态数据块,该数据块使用插件和示例规则配置全局记录器。
例 src/main/java/scorekeep/WebConfig.java-Recorder
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
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 示例应用程序。
可选:权限最低策略
您刚刚使用 AmazonS3FullAccess 和 AmazonDynamoDBFullAccess 安全策略部署了本教程。从长远来看,使用完全访问权限策略并不是最佳的做法。要提高所部署内容的安全性,请按照以下步骤更新权限。要了解有关 IAM 策略中安全最佳实践的更多信息,请参阅适用于 的 Identity and Access ManagementAmazonX-Ray.
要更新策略,您首先需要确定 Amazon S3 和 DynamoDB 资源的 ARN。然后,您可以在两个自定义 IAM 策略中使用 ARN。最后,将这些策略应用到实例配置文件。
标识 Amazon S3 资源
-
UNDER资源类型,按筛选方式Amazon S3 存储桶要找到您的应用程序使用的 Amazon S3 存储桶的 ARN。
-
选择资源标识符挂载到
elasticbeanstalk
. -
记录其完整的亚马逊资源名称。
-
将 ARN 插入到以下 IAM 策略中。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepS3", "Action": [ "s3:GetObject", "s3:PutObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::elasticbeanstalk-
region
-0987654321
" } ] }
标识 DynamoDB 资源
-
UNDER资源类型,按筛选方式AmazonDynamoDB 表要找到您的应用程序使用的 DynamoDB 表的 ARN。
-
选择资源标识符这是附加到其中一个
scorekeep
表格。 -
记录其完整的亚马逊资源名称。
-
将 ARN 插入到以下 IAM 策略中。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem" ], "Resource": "arn:aws:dynamodb:
region
:1234567890
:table/scorekeep-*" } ] }应用程序创建的表遵循一致的命名约定。您可以使用
scorekeep-*
格式来表明所有表均遵循该约定。
要更改 IAM 策略
-
在 IAM 控制台中打开 Elastic Beanstalk 实例配置文件:aws-elasticbeanstalk-ec2-role
。 -
从角色中删除 AmazonS3FullAccess 和 AmazonDynamoDBFullAccess 策略。
-
选择 Attach policies (附加策略),然后选择 Create policy (创建策略)。
-
选择 JSON 并粘贴之前创建的某个策略。
-
选择 Review policy (审核策略)。
-
对于 Name (名称),指定一个名称。
-
选择 Create policy(创建策略)。
-
将新创建的策略分配给
aws-elasticbeanstalk-ec2-role
。 -
对之前创建的第二个策略重复此操作。
清除
终止您的 Elastic Beanstalk 环境以关闭 Amazon EC2 实例、DynamoDB 表和其他资源。
终止 Elastic Beanstalk 环境
导航到管理控制台您的环境。
-
选择 Actions。
-
选择 Terminate Environment。
-
选择 Terminate (终止)。
在 30 天之后,跟踪数据自动从 X-Ray 中删除。
后续步骤
在下一章中了解有关 X-Ray 的更多信息,Amazon X-Ray 概念.
要分析自己的应用程序,请了解有关适用于 Java 的 X-Ray 软件开发工具包或其他 X-Ray 软件开发工具包
-
SDK for Java X-Ray–Amazon X-Ray SDK for Java
-
适用于 Node.js 的 Amazon X-Ray–Amazon适用于 Node.js 的 X-Ray SDK
-
SDK for .NET X-Ray–适用于 .NET 的Amazon X-Ray开发工具包
要在本地或上运行 X-Ray 守护进程Amazon请参阅Amazon X-Ray 守护程序.
要更好地了解 GitHub 上的示例应用程序,请参阅 eb-java-scorekeep