本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Trace Step Functions 请求数据 Amazon X-Ray
在 X-Ray 中跟踪数据

您可以使用 [Amazon X-Ray](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray.html) 可视化状态机的组件、确定性能瓶颈以及对导致错误的请求进行故障排除。状态机会向 X-Ray 发送跟踪数据，X-Ray 会处理这些数据，生成服务图和可搜索的跟踪摘要。

为状态机启用 X-Ray 后，您可以跟踪所有可用 X-Ray 的 Amazon 区域在 Step Functions 中执行的请求。这样，您就可以详细了解整个 Step Functions 请求的全貌。即使上游服务没有传递跟踪 ID，Step Functions 也会向 X-Ray 发送状态机执行的跟踪。您可以使用 X-Ray 服务地图来查看请求的延迟，包括与 X-Ray 集成的任何 Amazon 服务。您也可以配置采样规则，以根据您指定的标准指示 X-Ray 记录哪些请求以及以哪种采样率进行记录。

当状态机未启用 X-Ray 且上游服务未传递跟踪 ID 时，Step Functions 不会向 X-Ray 发送状态机执行的跟踪。但是，如果上游服务传递了跟踪 ID，Step Functions 就会向 X-Ray 发送状态机执行的跟踪。

在同时支持 Step Functions 的区域，你可以 Amazon X-Ray 与 Step Functions 一起使用。有关 X-Ray 和 Step Functions 的区域支持信息，请参阅 [Step Functions](https://docs.amazonaws.cn/general/latest/gr/step-functions.html) 和 [X-Ray](https://docs.amazonaws.cn/general/latest/gr/xray.html) 端点和配额页面。

**X-Ray 和 Step Functions 组合配额**  
您最多可以向跟踪中添加七天的数据，并查询三十天前的跟踪数据，即 X-Ray 存储跟踪数据的时间长度。您的跟踪将受到 X-Ray 配额的限制。除了其他配额外，X-Ray 还为 Step Functions 状态机提供了 100 KiB 的最小保证跟踪大小。如果向 X-Ray 提供的跟踪数据超过 100 KiB，可能会导致跟踪被冻结。有关 X-Ray 其他配额的更多信息，请参阅 [X-Ray 端点和配额](https://docs.amazonaws.cn/general/latest/gr/xray.html#limits_xray)页面的服务限额部分。

**重要**  
Step Functions 不支持对[*分布式 Map 状态*](state-map-distributed.md) 启动的子工作流执行进行 X-Ray 跟踪，因为此类执行很容易超出[跟踪文档大小限制](https://docs.amazonaws.cn/general/latest/gr/xray.html#limits_xray)。

**Topics**
+ [

## 设置和配置
](#xray-concept-create)
+ [

## 概念
](#xray-concepts)
+ [服务集成](#xray-concept-integrations)
+ [

## 查看 X-Ray 控制台
](#xray-concept-tracing-details)
+ [

## 查看 Step Functions 的 X-Ray 跟踪信息
](#concepts-xray-tracing-events)
+ [

## 跟踪
](#concepts-xray-traces)
+ [

## 服务图
](#concepts-xray-tracing-overview)
+ [

## 分段和子分段
](#concepts-xray-tracing-segments)
+ [

## 分析
](#concepts-xray-tracing-analytics)
+ [

## 配置
](#concepts-xray-tracing-config)
+ [

## 如果追踪视图或服务图中没有数据怎么办？
](#concepts-xray-troubleshooting)

## 设置和配置


### 创建状态机时启用 X-Ray 跟踪


通过在**指定详细信息**页面上选择**启用 X-Ray 跟踪**，即可在创建新状态机时启用 X-Ray 跟踪。

1. 打开 [Step Functions 控制台](https://console.amazonaws.cn/states/home)，然后选择**创建状态机**。

1. 在**选择创作方法**页面上，选择适当的选项来创建状态机。如果选择**运行示例项目**，则无法在创建状态机期间启用 X-Ray 跟踪，并且需要在创建状态机后启用 X-Ray 跟踪。有关在现有状态机中启用 X-Ray 的更多信息，请参阅[在现有状态机中启用 X-Ray](#xray-concept-enable-existing)。

   选择**下一步**。

1. 在**指定详细信息**页面，配置状态机。

1. 选择**启用 X-Ray 跟踪**。

    Step Functions 状态机现在将向 X-Ray 发送状态机执行的跟踪。
**注意**  
如果您选择使用现有 IAM 角色，则应确保允许 X-Ray 写入。有关您所需权限的更多信息，请参阅以下主题。

### Step Functions Amazon X-Ray 中使用的 IAM 策略


要启用 X-Ray 跟踪，您需要具有适当权限的 IAM 策略以允许跟踪。如果您的状态机使用其他集成服务，则可能需要其他 IAM 策略。有关特定服务集成，请参阅 IAM 政策。

 如果为现有状态机启用 X-Ray 跟踪，必须确保添加的策略有足够的权限来启用 X-Ray 跟踪。

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "xray:PutTraceSegments",
                "xray:PutTelemetryRecords",
                "xray:GetSamplingRules",
                "xray:GetSamplingTargets"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```

### 在现有状态机中启用 X-Ray


要在现有状态机中启用 X-Ray，请执行以下操作：

1. 在 [Step Functions 控制台](https://console.amazonaws.cn/states/home)中，选择要为其启用跟踪的状态机。

1. 选择**编辑**。

1. 选择**启用 X-Ray 跟踪**。

    您将看到一条通知，告知您可能需要进行其他更改。
**注意**  
为现有状态机启用 X-Ray 时，必须确保您的 IAM 策略授予了 X-Ray 执行跟踪的足够权限。您可以手动添加一个，也可以生成一个。有关更多信息，请参阅适用于 [Step Functions Amazon X-Ray 中使用的 IAM 策略](#xray-iam) 的 IAM 策略。

1. （可选）为状态机自动生成新角色，用于包含 X-Ray 权限。

1. 选择**保存**。

### 为 Step Functions 配置 X-Ray 跟踪


首次运行启用了 X-Ray 跟踪的状态机时，它将使用默认配置值进行 X-Ray 跟踪。 Amazon X-Ray 不会为发送到应用程序的每个请求收集数据。相反，它会为统计上显著数量的请求收集数据。默认情况下，每秒记录第一个请求，并记录所有其他请求的5% 。每秒一个请求是*容器*。这可确保只要服务正在处理请求，就会每秒至少记录一个跟踪。5% 是对超出容器尺寸的额外请求进行采样的*比率*。

为避免在您入门时产生服务费用，保守做法是使用默认采样率。您可以配置 X-Ray 以修改默认采样规则并配置基于服务或请求的属性应用采样的其他规则。

例如，您可能想要禁用采样并跟踪所有修改状态或句柄 Amazon Web Services 账户 或事务的呼叫的请求。对于量非常大的只读调用，例如后台轮询、运行状况检查或连接维护，您采用较低的采样率仍可获取足够的数据来观察出现的任何问题。

要为状态机配置采样规则，请执行以下操作：

1. 前往 [X-Ray 控制台](https://console.amazonaws.cn/xray/home)。

1. 选择**采样**。

1. 要创建规则，请选择**创建采样规则**。

   要编辑规则，请选择规则的名称。

   要删除规则，请选择一条规则并使用**操作**菜单来删除它。

现有采样规则的某些部分（例如名称和优先级）无法更改。相反，您可以添加或克隆现有规则，进行所需的更改，然后使用新规则。

有关 X-Ray 采样规则以及如何配置各种参数的详细信息，请参阅在 [X-Ray 控制台中配置采样规则](https://docs.amazonaws.cn/xray/latest/devguide/xray-console-sampling.html)。

### 集成上游服务


要将 Step Functions 工作流程（例如快速、同步和标准工作流）的执行与上游服务集成，您需要设置 `traceHeader`。如果您使用的是 API Gateway 中的 HTTP API，则系统会自动为您完成此操作。但是，如果您使用的是 Lambda 函数 and/or 、软件开发工具包，则需要自己设置[https://docs.amazonaws.cn/step-functions/latest/apireference/API_StartExecution.html](https://docs.amazonaws.cn/step-functions/latest/apireference/API_StartExecution.html)或 [https://docs.amazonaws.cn/step-functions/latest/apireference/API_StartSyncExecution.html](https://docs.amazonaws.cn/step-functions/latest/apireference/API_StartSyncExecution.html)API 调用。`traceHeader`

您必须将 `traceHeader` 格式指定为 `\p{ASCII}∗`。此外，要让 Step Functions 使用相同的跟踪 ID，必须将格式指定为 `Root={TRACE_ID};Sampled={1 or 0}`。如果您使用的是 Lambda 函数，请将 `TRACE_ID` 替换为当前分段中的跟踪 ID，如果采样模式为 true，则将“已采样”字段设为 `1`，如果采样模式为 false，则设为 `0`。以这种格式提供跟踪 ID 可确保您获得完整的追踪信息。

下面是使用 Python 编写的示例，展示如何指定 `traceHeader`。

```
state_machine = config.get_string_paramter("STATE_MACHINE_ARN")
    if (xray_recorder.current_subsegment() is not None and 
        xray_recorder.current_subsegment().sampled) :
        trace_id = "Root={};Sampled=1".format(
            xray_recorder.current_subsegment().trace_id
        )
    else:
        trace_id = "Root=not enabled;Sampled=0"
    LOGGER.info("trace %s", trace_id)
    
    # execute it
    response = states.start_sync_execution(
        stateMachineArn=state_machine,
        input=event['body'],
        name=context.aws_request_id,
        traceHeader=trace_id
    )
    LOGGER.info(response)
```

**X-Ray 在标题或有效载荷中进行跟踪**  
 对于 X-Ray 跟踪，所有 Amazon 服务都使用 HTTP 请求中的`X-Amzn-Trace-Id`标头。使用标头是识别跟踪的首选机制。`StartExecution` 和 `StartSyncExecution` API 操作也可以从请求有效载荷的正文使用 `traceHeader`。如果**同时提供了两个**来源，则 Step Functions 将使用标**头值**（首选）而不是请求正文中的值。

## 概念


### X-Ray 控制台


在 Amazon X-Ray 控制台中，当状态机启用 X-Ray 时，您可以查看应用程序所处理的请求的服务映射和跟踪。

有关如何访问状态机执行的 X-Ray 控制台的信息，请参阅[查看 X-Ray 控制台](#xray-concept-tracing-details)。

有关 X-Ray 控制台的详细信息，请参阅 [X-Ray 控制台文档](https://docs.amazonaws.cn/xray/latest/devguide/xray-console.html)。

### 分段、子分段和跟踪


**分段**记录有关向状态机发出的请求信息。它包含诸如状态机执行的工作之类的信息，也可能包含有关下游调用信息的**子分段**。

**跟踪**会收集单个请求生成的所有分段。

### 采样


为确保高效跟踪并为应用程序所服务的请求提供代表性样本，X-Ray 应用**采样**算法来确定跟踪哪些请求。这可以通过编辑采样规则来更改。

### 指标


对于状态机，X-Ray 将测量调用时间、状态转换时间、Step Functions 的总体执行时间以及执行时间的差异。这些信息可通过 X-Ray 控制台获取。

### 分析


 Amazon X-Ray Analytics 控制台是一款用于解释跟踪数据的交互式工具。您可以通过单击与当前跟踪集关联的指标和字段的图表和面板，使用越来越精细的筛选条件细化活动的数据集。可以分析状态机的执行情况来定位和识别性能问题。

有关 X-Ray 分析的详细信息，请参阅[与 Analy Amazon X-Ray tics 控制台交互](https://docs.amazonaws.cn/xray/latest/devguide/xray-console-analytics.html)

## Step Functions 服务集成和 X-Ray
服务集成

 一些与 Step Functions 集成的 Amazon 服务 Amazon X-Ray 通过向请求添加跟踪标头、运行 X-Ray 守护程序或做出采样决策并将跟踪数据上传到 X-Ray 来提供集成。其他人必须使用 Amazon X-Ray SDK 进行检测。还有一些服务尚未支持 X-Ray 集成。在使用与 Step Functions 集成的服务时，X-Ray 集成是提供完整跟踪数据的必要条件 

### 原生 X-Ray 支持


使用原生 X-Ray 支持的服务集成包括：
+ [Amazon Simple Notification Service](https://docs.amazonaws.cn/xray/latest/devguide/xray-services-sns.html)
+ [Amazon Simple Queue Service](https://docs.amazonaws.cn/xray/latest/devguide/xray-services-sqs.html)
+ [Amazon Lambda](https://docs.amazonaws.cn/xray/latest/devguide/xray-services-lambda.html)
+ Amazon Step Functions

### 所需检测


需要 [X-Ray 检测](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray.html)的服务集成：
+ Amazon Elastic Container Service
+ Amazon Batch
+ Amazon Fargate

### 仅客户端跟踪


其他服务集成不支持 X-Ray 跟踪。但是，仍然可以收集客户端跟踪：
+ Amazon DynamoDB
+ Amazon EMR
+ 亚马逊 SageMaker AI
+ Amazon CodeBuild
+ Amazon Glue

## 查看 X-Ray 控制台


X-Ray 从服务以分段形式接收数据。然后，X-Ray 将具有共同请求的分段分组为跟踪。X-Ray 处理跟踪以生成服务图，服务图提供您的应用程序的可视化表示形式。

启动状态机执行后，在**执行详细信息**部分选择 **X-Ray 跟踪视图**链接，即可查看其 X-Ray 跟踪。

为状态机启用 X-Ray 后，则可以在 X-Ray 控制台中查看其执行跟踪信息。

## 查看 Step Functions 的 X-Ray 跟踪信息


以下步骤说明启用 X-Ray 并运行执行后，您可以在控制台中看到的信息类型。展示了 [使用 Amazon SQS、Amazon SNS 和 Lambda 创建回调模式示例](callback-task-sample-sqs.md) 示例项目的 X-Ray 跟踪。

## 跟踪


执行完成后，您可以导航到 X-Ray 控制台，在此处可以看到 X-Ray **跟踪**页面。这将显示服务图的概述以及状态机的跟踪和分段信息。

![\[状态机的 X-Ray 跟踪的说明性屏幕截图。\]](http://docs.amazonaws.cn/step-functions/latest/dg/images/xray-tracing-overview.png)


## 服务图


X-Ray 控制台中的服务图可帮助您识别发生错误的服务、存在高延迟连接的服务，或查看请求不成功的跟踪。

![\[侧重于 X-Ray 跟踪中的服务图的说明性屏幕截图。\]](http://docs.amazonaws.cn/step-functions/latest/dg/images/xray-tracing-servicemap.png)


在跟踪视图中，您可以选择一个服务节点来查看该节点的请求，或选择两个节点之间的边缘来查看经过该连接的请求。在这里，`WaitForCallBack` 节点已被选中，您可以查看有关其执行和响应状态的其他信息。

![\[X-Ray 跟踪节点的详细信息示例。\]](http://docs.amazonaws.cn/step-functions/latest/dg/images/xray-tracing-servicemap-detail.png)


您可以看到 X-Ray 服务图如何与状态机相关联。只要支持 X-Ray，Step Functions 调用的每个服务集成都有一个服务图节点。

![\[正在跟踪的状态机的图形表示示例。\]](http://docs.amazonaws.cn/step-functions/latest/dg/images/sample-callback-example.png)


## 分段和子分段


**跟踪**是由单个请求生成的**片段**集合。每个分段提供资源的名称、有关请求的详细信息以及有关所完成工作的详细信息。在**跟踪**页面上，您可以看到分段，如果展开，还可以看到其相应的子分段。您可以选择一个分段或子分段来查看其详细信息。

服务图上的每个节点都有不同的分段。

![\[状态机的分段和子分段的屏幕截图示例。\]](http://docs.amazonaws.cn/step-functions/latest/dg/images/xray-tracing-segments.png)


选择分段可提供资源的名称、有关请求的详细信息以及有关所完成工作的详细信息。

分段可以将关于已完成工作的数据细分为子分段。选择子分段可显示精细的时间信息和详细信息。子分段可以包含有关调用 Amazon 服务、外部 HTTP API 或 SQL 数据库的其他详细信息。

## 分析




 Amazon X-Ray **Analytics** 控制台是一款用于解释跟踪数据的交互式工具。您可以使用它来更轻松地了解状态机的性能。可以通过交互式响应时间和时间序列图来探索、分析和可视化跟踪，以便协助定位性能和延迟问题。

您可以通过单击与当前跟踪集关联的指标和字段的图表和面板，使用越来越精细的筛选条件细化活动的数据集。

## 配置


您可以从 X-Ray 控制台配置采样和加密选项。
+  选择**采样**，查看有关采样率和配置的详细信息。

  您可以更改采样规则来控制记录的数据量，并修改采样行为来满足您的特定要求。
+ 选择**加密**可修改加密设置。

  可以使用默认设置，其中 X-Ray 对跟踪和静态数据进行加密，或者，如果需要，可以选择 KMS 密钥。标准 [Amazon KMS](https://docs.amazonaws.cn/kms/latest/developerguide/) 会对后一种情况收费。

## 如果追踪视图或服务图中没有数据怎么办？


如果您启用了 X-Ray，但在 X-Ray 控制台中看不到任何数据，请检查：
+ IAM 角色设置是否正确，允许写入 X-Ray。
+ 采样规则是否允许对数据进行采样。
+ 由于在应用新创建或修改的 IAM 角色之前可能会有短暂延迟，因此请在几分钟后再次检查跟踪或服务图。
+ 如果您在 X-Ray Traces 面板中看到 “**未找到数据**”，请检查您的 [IAM 账户设置](https://console.amazonaws.cn/iam/home?#/account_settings)并确保已 Amazon Security Token Service 为目标区域启用该设置。有关更多信息，请参阅 *IAM 用户指南 Amazon STS Amazon Web Services 区域*[中的激活和停用](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)。