AWS X-Ray 入门 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS X-Ray 入门

要开始使用 AWS X-Ray,请在 Elastic Beanstalk 中启动已分析的示例应用程序以生成跟踪数据。在几分钟内,您可以启动示例应用程序,生成流量,将分段发送到 X-Ray,以及在 AWS 管理控制台中查看服务图和跟踪。

本教程使用示例 Java 应用程序生成分段并将其发送到 X-Ray。该应用程序使用 Spring 框架实施 JSON Web API 和 AWS SDK for Java,以将数据保存到 Amazon DynamoDB。应用程序中的 servlet 筛选器分析该应用程序处理的所有传入请求,而 AWS 开发工具包客户端上的请求处理程序分析对 DynamoDB 的下游调用。


      Scorekeep 示例应用程序流

您可以使用 X-Ray 控制台查看服务地图中客户端、服务器和 DynamoDB 之间的连接。服务地图是组成 Web 应用程序的服务的可视化形式,利用在处理请求时生成的跟踪数据生成。


      查看服务地图中客户端、服务器和 DynamoDB 之间的连接

借助 X-Ray SDK for Java,通过进行两项配置更改,您可以跟踪自己应用程序的所有主要和下游 AWS 资源:

  • WebConfig 类或 web.xml 文件中,向 servlet 配置中添加X-Ray SDK for Java的跟踪筛选器。

  • 将 X-Ray SDK for Java 子模块作为 Maven 或 Gradle 生成配置中的生成依赖项。

您也可以通过使用 AWS CLI 调用 X-Ray API 来访问原始服务地图和跟踪数据。服务地图和跟踪数据是 JSON,您可以进行查询以确保您的应用程序发送数据,也可作为测试自动化的一部分检查特定字段。

先决条件

本教程使用 Elastic Beanstalk 创建和配置资源,以运行示例应用程序和 X-Ray 守护程序。如果您使用具有有限权限的 IAM 用户,则添加 Elastic Beanstalk 托管用户策略来赋予其使用 Elastic Beanstalk 的权限,并添加 AWSXrayReadOnlyAccess 托管策略来赋予其在 X-Ray 控制台中读取服务地图和跟踪的权限。

为示例应用程序创建 Elastic Beanstalk 环境。如果您以前未使用过 Elastic Beanstalk,这还将为您的应用程序创建一个服务角色和实例配置文件。在您要在其中部署示例应用程序的区域中必须存在一个默认 VPC,否则 Elastic Beanstalk 将无法部署该应用程序。

创建 Elastic Beanstalk 环境

  1. 通过以下预配置链接打开 Elastic Beanstalk 管理控制台:https://console.amazonaws.cn/elasticbeanstalk/#/newApplication?applicationName=scorekeep&solutionStackName=Java

  2. 选择 Create application 创建一个应用程序以及运行 Java 8 SE 平台的环境。

  3. 当您的环境准备就绪后,控制台会将您重定向到环境控制面板。

  4. 单击页面顶部的 URL 以打开站点。

您环境中的实例需要权限来将数据发送到 AWS X-Ray 服务。此外,该示例应用程序使用 Amazon S3 和 DynamoDB。修改默认的 Elastic Beanstalk 实例配置文件以包含使用这些服务的权限。

将 X-Ray、Amazon S3 和 DynamoDB 权限添加到您的 Elastic Beanstalk 环境

  1. 在 IAM 控制台中打开 Elastic Beanstalk 实例配置文件:aws-elasticbeanstalk-ec2-role

  2. 选择附加策略

  3. AWSXrayFullAccessAmazonS3FullAccessAmazonDynamoDBFullAccess 附加到角色。

    注意

    完全访问权限策略不是适合一般使用的最佳做法。有关配置具有最低权限的策略以减少安全风险的说明,请参阅可选:最低权限策略

部署到 Elastic Beanstalk 并生成跟踪数据

将示例应用程序部署到您的 Elastic Beanstalk 环境。示例应用程序使用 Elastic Beanstalk 配置文件来配置与 X-Ray 一起使用的环境,并创建它自动使用的 DynamoDB。

部署源代码

  1. 下载示例应用程序:eb-java-scorekeep-xray-gettingstarted-v1.3.zip

  2. Open the Elastic Beanstalk console.

  3. Navigate to the management console for your environment.

  4. 选择 Upload and Deploy

  5. 上传 eb-java-scorekeep-xray-gettingstarted-v1.3.zip,然后选择 Deploy (部署)

示例应用程序包括一个前端 Web 应用程序。使用 Web 应用程序来生成 API 流量并将跟踪数据发送到 X-Ray。

生成跟踪数据

  1. 在环境控制面板中,单击相应的 URL 以打开 Web 应用程序。

  2. 选择 Create 来创建用户和会话。

  3. 键入 game name,将 Rules 设置为 Tic Tac Toe,然后选择 Create 创建一个游戏。

  4. 选择 Play 以启动游戏。

  5. 选择平铺可进行移动和更改游戏状态。

上述每个步骤都会生成到 API 的 HTTP 请求,并对 DynamoDB 进行下游调用,以读取和写入用户、会话、游戏、移动和状态数据。

在 X-Ray 控制台中查看服务地图

您可以在 X-Ray 控制台中查看示例应用程序生成的服务地图和跟踪。

要使用 X-Ray 控制台

  1. 打开 X-Ray 控制台的服务地图页面。

  2. 控制台将显示该服务的图形表示形式,这是由 X-Ray 利用应用程序发送的跟踪数据生成的。

    

            X-Ray 根据应用程序发送的跟踪数据生成的服务图的表示形式

该服务地图显示 Web 应用程序客户端、在 Elastic Beanstalk 中运行的 API、DynamoDB 服务以及应用程序使用的每个 DynamoDB 表。对应用程序的每个请求 (最多为可配置的每秒最大请求数) 都受到跟踪 (因为请求到达 API),生成针对下游服务的请求,然后完成。

可以在服务图中选择任一节点,来查看对该节点生成流量的请求的跟踪。目前,Amazon SNS 节点为红色。深入了解原因。

查找错误原因

  1. 选择名为 SNS 的节点。Service details panel (服务详细信息面板) 随即在右侧打开。

  2. 选择查看跟踪以访问 Trace 概述屏幕。

  3. Trace list 中选择跟踪。该跟踪没有方法或 URL,因为它是在启动期间记录的,而不是对传入请求的响应。

    
            从跟踪列表中选择跟踪
  4. 选择红色的状态图标以打开 SNS 子分段的 Exceptions 页面。

    

            选择红色的状态图标将打开 SNS 子分段的“Exceptions (异常)”页面
  5. X-Ray 开发工具包会自动捕获由已分析的 AWS 开发工具包客户端引发的异常并记录堆栈跟踪。

    
            显示捕获的异常和记录的堆栈跟踪的“Exceptions (异常)”选项卡

原因指出,在 WebConfig 类中,调用 createSubscription 时所提供的电子邮件地址无效。让我们修复这一问题。

配置 Amazon SNS 通知

当用户完成游戏时,Scorekeep 使用 Amazon SNS 发送通知。当应用程序启动时,它试图为在环境变量中定义的电子邮件地址创建订阅。该调用目前失败,导致服务地图中的 Amazon SNS 节点变为红色。在环境变量中配置通知电子邮件,以启用通知并使服务地图变为绿色。

为 Scorekeep 配置 Amazon SNS 通知

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management console for your environment.

  3. Choose Configuration.

  4. 选择 Software Configuration

  5. Environment Properties 下,用您的电子邮件地址替换默认值。

    
            设置环境属性
    注意

    默认值使用 AWS CloudFormation 函数来检索存储在配置文件中的参数(在这种情况下为虚值)。

  6. 选择 Apply

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


        更新后的服务地图

浏览示例应用程序

在 Java 中示例应用程序是一个 HTTP Web API,可配置为使用 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、方法、响应状态、开始时间和结束时间。


        控制台中的主服务节点

应用程序还会使用 AWS SDK for Java 对 DynamoDB 进行下游调用。要分析这些调用,应用程序只需采用 AWS 开发工具包相关的子模块作为依赖项,X-Ray SDK for Java 会自动分析所有 AWS 开发工具包客户端。

应用程序使用 Buildfile 文件在实例上生成源代码,同时使用 GradleProcfile 文件运行 Gradle 生成的可执行 JAR。BuildfileProcfile 支持是 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.4.0") } }

只需拥有核心、AWS 开发工具包和 AWS 开发工具包 Instrumentor 子模块就可以自动分析 AWS 开发工具包进行的所有下游调用。

要运行 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

X-Ray SDK for Java提供了一个名为 AWSXRay 的类,该类提供全局记录器,即您可用于分析代码的 TracingHandler。您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的 AWSXRayServletFilter。示例包括 WebConfig 类中的一个静态数据块,该数据块使用插件和示例规则配置全局记录器。

例 src/main/java/scorekeep/WebConfig.java - 记录器

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 调用。有关更多信息,请参阅AWS X-Ray 示例应用程序

可选:最低权限策略

您刚刚使用 AmazonS3FullAccessAmazonDynamoDBFullAccess 安全策略部署了本教程。从长远来看,使用完全访问权限策略并不是最佳的做法。要提高所部署内容的安全性,请按照以下步骤更新权限。要了解有关 IAM 策略的安全性最佳实践的更多信息,请参阅适用于 AWS X-ray 的 Identity and Access Management

要更新策略,您首先需要确定 Amazon S3 和 DynamoDB 资源的 ARN。然后,在两个自定义 IAM 策略中使用这两个 ARN。最后,将这些策略应用到实例配置文件。

标识您的 Amazon S3 资源

  1. 打开 AWS Config 控制台的“Resources”(资源)页面

  2. Resource type (资源类型) 下,按 AWS S3 Bucket (AWS S3 存储桶) 进行筛选,以找到您的应用程序使用的 Amazon S3 存储桶的 ARN。

  3. 选择附加到 elasticbeanstalk资源标识符

  4. 记录其完整的亚马逊资源名称

  5. 将 ARN 插入到以下 IAM 策略中。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepS3", "Action": [ "s3:GetObject", "s3:PutObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::elasticbeanstalk-region-0987654321" } ] }

标识您的 DynamoDB 资源

  1. 打开 AWS Config 控制台的“Resources”(资源)页面

  2. Resource type (资源类型) 下,按 AWS DynamoDB Table (AWS DynamoDB 表) 进行筛选,以找到您的应用程序使用的 DynamoDB 表的 ARN。

  3. 选择附加到其中一个 scorekeep 表的资源标识符

  4. 记录其完整的亚马逊资源名称

  5. 将 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 策略

  1. 在 IAM 控制台中打开 Elastic Beanstalk 实例配置文件:aws-elasticbeanstalk-ec2-role

  2. 从角色中删除 AmazonS3FullAccessAmazonDynamoDBFullAccess 策略。

  3. 选择 Attach policies (附加策略),然后选择 Create policy (创建策略)

  4. 选择 JSON 并粘贴之前创建的某个策略。

  5. 选择查看策略

  6. 对于 Name (名称),指定一个名称。

  7. 选择 Create policy

  8. 将新创建的策略分配给 aws-elasticbeanstalk-ec2-role

  9. 对之前创建的第二个策略重复此操作。

清除

终止您的 Elastic Beanstalk 环境以关闭 Amazon EC2 实例、DynamoDB 表和其他资源。

终止 Elastic Beanstalk 环境

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management console for your environment.

  3. 选择 Actions

  4. 选择 Terminate Environment

  5. 选择 Terminate

在 30 days 之后,跟踪数据自动从 X-Ray 中删除。

后续步骤

要了解有关 X-Ray 的更多信息,请参阅下一章 AWS X-Ray 概念

要分析您自己的应用程序,请了解有关X-Ray SDK for Java或其他某个 X-Ray 开发工具包的更多信息:

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

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