本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 Step Functions 中查看 X-Ray 跟踪
在本教程中，您将学习如何使用 X-Ray 来跟踪运行状态机时发生的错误。您可以使用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) 可视化状态机的组件、确定性能瓶颈以及对导致错误的请求进行故障排除。在本教程中，您将创建多个随机生成错误的 Lambda 函数，然后可以使用 X-Ray 对其进行跟踪和分析。
[创建使用 Lambda 的 Step Functions 状态机](tutorial-creating-lambda-state-machine.md)教程将引导您创建一个调用 Lambda 函数的状态机。如果您已完成该教程，请跳至[第 2 步](#create-xray-lambda-state-machine-step-4)，并使用之前创建的 AWS Identity and Access Management (IAM) 角色。
## 第 1 步：为 Lambda 创建 IAM 角色。
AWS Lambda 和 AWS Step Functions 都可以运行代码和访问 AWS 资源（例如，存储在 Amazon S3 存储桶中的数据）。为了保持安全性，您必须授予 Lambda 和 Step Functions 对这些资源的访问权。
Lambda 要求您在创建 Lambda 函数时分配一个 AWS Identity and Access Management (IAM) 角色，就像 Step Functions 要求您在创建状态机时分配 IAM 角色一样。
### 创建用于 Lambda 的角色
您可使用 IAM 控制台创建服务相关角色。
**创建角色（控制台）**
1. 登录 AWS 管理控制台 并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在 IAM 控制台的导航窗格中，选择**角色**。然后选择**创建角色**。
1. 选择 **AWS 服务**角色类型，然后选择 **Lambda**。
1. 选择 **Lambda** 使用案例。使用案例由服务定义以包含服务所需的信任策略。然后选择**下一步：权限**。
1. 选择一个或多个要附加到角色的许可策略（例如，`AWSLambdaBasicExecutionRole`）。请参阅 [AWS Lambda 权限模型](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)。
选中用于分配您希望角色拥有的权限的策略旁的框，然后选择**下一步: 审核**。
1. 输入**角色名称**。
1. （可选）对于**角色描述**，编辑新服务相关角色的描述。
1. 检查该角色，然后选择**创建角色**。
## 第 2 步：创建 Lambda 函数
您的 Lambda 函数将随机抛出错误或超时，生成要在 X-Ray 中查看的示例数据。
**重要**
确保您的 Lambda 函数与 AWS 区域 状态机位于同一个 AWS 账户下。
1. 打开 [Lambda 控制台](https://console.aws.amazon.com/lambda/home)，然后选择**创建函数**。
1. 在**创建函数**部分中，选择**从头开始创作**。
1. 在**基本信息**部分中，配置您的 Lambda 函数：
1. 对于**函数名称**，请输入 `TestFunction1`。
1. 对于**运行时系统**，选择 **Node.js 18.x**。
1. 对于**角色**，选择**选择现有角色**。
1. 对于**现有角色**，选择[您之前创建的 Lambda 角色](#create-xray-lambda-state-machine-to-create-a-role-for-use-with-lambda)。
**注意**
如果您创建的 IAM 角色未显示在列表中，该角色可能仍需要几分钟才能传播到 Lambda。
1. 选择**创建函数**。
创建您的 Lambda 函数后，记下页面右上角的 Amazon 资源名称 (ARN)。例如：
```
arn:aws:lambda:{{region}}:123456789012:function:TestFunction1
```
1. 将以下 Lambda 函数代码复制到页面的****{{TestFunction1}}**函数代码**部分。
```
function getRandomSeconds(max) {
return Math.floor(Math.random() * Math.floor(max)) * 1000;
}
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
export const handler = async (event) => {
if(getRandomSeconds(4) === 0) {
throw new Error("Something went wrong!");
}
let wait_time = getRandomSeconds(5);
await sleep(wait_time);
return { 'response': true }
};
```
此代码会创建随机定时的故障，这些故障将用于在状态机中生成示例错误，可使用 X-Ray 跟踪进行查看和分析。
1. 选择**保存**。
## 第 3 步：再创建两个 Lambda 函数
再创建两个 Lambda 函数。
1. 重复第 2 步，再创建两个 Lambda 函数。对于第二个函数，在**函数名称**中输入 `TestFunction2`。对于第三个函数，在**函数名称**中输入 `TestFunction3`。
1. 在 Lambda 控制台中，检查您现在是否有三个 Lambda 函数：`TestFunction1`、`TestFunction2` 和 `TestFunction3`。
## 第 4 步：创建状态机
在本步骤中，您将使用 [Step Functions 控制台](https://console.aws.amazon.com/states/home?region=us-east-1#/)创建具有三个 `Task` 状态的状态机。每个 `Task` 状态都将引用您的三个 Lambda 函数中的一个。
1. 打开 [Step Functions 控制台](https://console.aws.amazon.com/states/home)，从菜单中选择**状态机**，然后选择**创建状态机**。
**重要**
[确保您的状态机与您之前在[步骤 2 和步骤 3](#create-xray-lambda-state-machine-step-2) 中创建的 Lambda 函数位于相同的 AWS 账户和区域下。](#create-xray-lambda-state-machine-step-3)
1. 选择**从空白创建**。
1. 为状态机命名，然后选择**继续**，在 Workflow Studio 中编辑状态机。
1. 在本教程中，您将在[代码编辑器](workflow-studio.md#wfs-interface-code-editor)中编写状态机的 [Amazon States Language](concepts-amazon-states-language.md) (ASL) 定义。要执行此操作，请选择**代码**。
1. 删除现有的样板代码并粘贴以下代码。在任务状态定义中，请记住将示例 ARNs 替换为您创建的 ARNs Lambda 函数。
```
{
"StartAt": "CallTestFunction1",
"States": {
"CallTestFunction1": {
"Type": "Task",
"Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function1}}",
"Catch": [
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "CallTestFunction2"
},
"CallTestFunction2": {
"Type": "Task",
"Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function2}}",
"Catch": [
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "CallTestFunction3"
},
"CallTestFunction3": {
"Type": "Task",
"Resource": "{{arn:aws:lambda:{{region}}:123456789012:function:test-function3}}",
"TimeoutSeconds": 5,
"Catch": [
{
"ErrorEquals": [
"States.Timeout"
],
"Next": "AfterTimeout"
},
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "Succeed"
},
"Succeed": {
"Type": "Succeed"
},
"AfterTimeout": {
"Type": "Fail"
},
"AfterTaskFailed": {
"Type": "Fail"
}
}
}
```
这是使用 Amazon States Language 的状态机的说明。它定义了三个名为 `CallTestFunction1`、`CallTestFunction2` 和 `CallTestFunction3` 的 `Task` 状态。每个状态都会调用您的三个 Lambda 函数中的一个。有关更多信息，请参阅[状态机结构](statemachine-structure.md)。
1. 为状态机指定一个名称。为此，请选择默认状态机名称旁边的编辑图标**MyStateMachine**。然后，找到**状态机配置**，在**状态机名称**框中指定一个名称。
对于本教程，请输入名称 **TraceFunctions**。
1. （可选）在**状态机配置**中，指定其他工作流设置，例如状态机类型及其执行角色。
在本教程中，在**其他配置**下，选择**启用 X-Ray 跟踪**。保留**状态机设置**中的所有其他默认选项。
如果您之前为状态机[创建了具有正确权限的 IAM 角色](procedure-create-iam-role.md)并想使用该角色，请在**权限**中选择**选择现有角色**，然后从列表中选择一个角色。或者选择**输入角色 ARN**，然后为该 IAM 角色的 ARN 获取该角色。
1. 在**确认角色创建**对话框中，选择**确认**继续。
您也可以选择**查看角色设置**，返回至**状态机配置**。
**注意**
如果您删除了 Step Functions 创建的 IAM 角色，Step Functions 在以后无法重新创建该角色。同样，如果您修改了该角色（例如，通过在 IAM 策略中从主体中删除 Step Functions），Step Functions 在以后也无法还原其原始设置。
## 第 5 步：运行状态机
状态机执行是指运行工作流执行任务的实例。
1. 在**{{TraceFunctions}}**页面上，选择 “**开始执行**”。
此时将显示**新执行**页面。
1. 在**启动执行**对话框中，执行以下操作：
1. （可选）输入自定义执行名称，以便覆盖生成的默认执行名称。
**非 ASCII 名称和日志记录**
Step Functions 对于状态机、执行、活动和标签接受包含非 ASCII 字符的名称。由于此类字符会 CloudWatch 阻止亚马逊记录数据，因此我们建议您仅使用 ASCII 字符，这样您就可以跟踪 Step Functions 的指标。
1. 选择**启动执行**。
1. Step Functions 控制台会将您引导到一个以您的执行 ID 为标题的页面。该页面被称为*执行详细信息*页面。在此页面上，您可以随着执行的进展或者在执行完成后查看执行结果。
要查看执行结果，请在**图表视图**上选择各个状态，然后在[步骤详细信息](concepts-view-execution-details.md#exec-details-intf-step-details)窗格中选择各个选项卡，分别查看每个状态的详细信息，包括输入、输出和定义。有关可在*执行详细信息*页面上查看的执行信息的详细信息，请参阅[执行详细信息概览](concepts-view-execution-details.md#exec-details-interface-overview)。
运行几次（至少三次）执行。
1. 执行完成后，点击 **X-Ray 追踪映射**链接。您可以在执行仍在运行时查看跟踪，但您可能希望在查看 X-Ray 跟踪映射之前先查看执行结果。
1. 查看服务图来识别错误发生的位置、具有高延迟的连接或针对不成功请求的跟踪。在此示例中，您可以看到每个函数接收了多少流量。`TestFunction2` 被调用的频率高于 `TestFunction3`，`TestFunction1` 被调用的频率是 `TestFunction2` 的两倍多。
服务地图根据成功调用与错误和故障的比率为每个节点显示颜色，从而指示节点的运行状况：
+ **绿色**表示成功调用
+ **红色**表示服务器故障（500 系列错误）
+ **黄色**表示客户端错误（400 系列错误）
+ **紫色**表示限制错误（429 请求过多）
您也可以选择一个服务节点来查看该节点的请求，或选择两个节点之间的边缘来查看经过该连接的请求。
1. 查看 X-Ray 跟踪映射，了解每次执行时发生了什么。时间线视图显示分段和子分段的层次结构。列表中的第一个条目为分段，表示服务为单个请求记录的所有数据。分段的下一级是子分段。此示例显示了 Lambda 函数记录的子分段。
有关理解 X-Ray 跟踪以及使用 X-Ray 和 Step Functions 的更多信息，请参阅 [Trace Step Functions 请求数据 AWS X-Ray](concepts-xray-tracing.md)