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

# Amazon X-Ray 概念
概念

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

**Topics**
+ [

## 客户细分
](#xray-concepts-segments)
+ [

## 子分段
](#xray-concepts-subsegments)
+ [

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

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

## 采样
](#xray-concepts-sampling)
+ [

## 跟踪标头
](#xray-concepts-tracingheader)
+ [

## 筛选条件表达式
](#xray-concepts-filterexpressions)
+ [

## 组
](#xray-concepts-groups)
+ [

## 注释和元数据
](#xray-concepts-annotations)
+ [

## 错误、故障和异常
](#xray-concepts-errors)

## 客户细分


运行您的应用程序逻辑的计算资源发送关于其工作的数据作为**分段**。分段提供资源的名称、有关请求的详细信息以及有关所完成工作的详细信息。例如，当 HTTP 请求到达您的应用程序时，它可以记录下列相关数据：
+ **主机** - 主机名、别名或 IP 地址
+ **请求** - 方法，客户端地址、路径、用户代理
+ **响应** - 状态、内容
+ **所完成工作** - 开始和结束时间、子分段
+ **发生的错误** - [错误、故障和异常](#xray-concepts-errors)，包括自动捕获的异常堆栈。

![\[X-Ray 跟踪的分段数据\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-cw-segment-overview.png)


X-Ray SDK 从请求和响应标头、应用程序中的代码以及它在其上运行的 Amazon 资源的相关元数据收集信息。您可以通过修改应用程序配置或代码来选择要收集的数据，以检测传入请求、下游请求和 Amazon SDK 客户端。

**转发的请求**  
如果负载均衡器或其他中间将请求转发到您的应用程序，X-Ray 会提取请求 `X-Forwarded-For` 标头中的客户端 IP 而非 IP 数据包中的源 IP。由于转发的请求记录的客户端 IP 可以伪造，因此不应信任。

您可以使用 X-Ray SDK 来记录其他信息，如[注释和元数据](#xray-concepts-annotations)。有关分段和子分段中记录的结构和信息的详情，请参阅 [Amazon X-Ray 分段文档](xray-api-segmentdocuments.md)。分段文档的大小最大可以是 64KB。

## 子分段


分段可以将关于已完成工作的数据细分为**子分段**。子分段提供有关您的应用程序为满足原始请求而进行的下游调用的更精细的计时信息和详情。子分段可以包含对 Amazon Web Services 服务调用、外部 HTTP API 或 SQL 数据库的相关额外详细信息。您甚至可以定义任意子分段以检测特定函数或应用程序中的代码行。

![\[子分段提供更精细的信息\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-cw-timeline-segment.png)


对于不发送自己的分段的服务（如 Amazon DynamoDB），X-Ray 使用子分段在跟踪地图上生成*推断分段* 和下游节点。这样您可以查看所有下游依赖项，即使它们不支持跟踪或者是外部依赖项也是如此。

子分段表示从您应用程序的角度将下游调用视为客户端。如果还会检测下游服务，则它发送的分段会替换从上游客户端的子分段生成的推断分段。服务图上的节点使用来自服务分段的信息 (如果可用)，而两个节点之间的边缘节点使用上游服务的子分段。

例如，当您使用检测的 Amazon SDK 客户端调用 DynamoDB 时，X-Ray SDK 会为该调用记录子分段。DynamoDB 不发送分段，因此跟踪中的推断分段、服务图上的 DynamoDB 节点以及您的服务与 DynamoDB 之间的边缘节点全都包含来自子分段的信息。

![\[检测过的应用程序与 DynamoDB 之间的边缘节点。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-cw-servicemap-ddb-edge.png)


当您使用检测的应用程序调用另一个检测的服务时，下游服务会发送自己的分段，以从自己的角度记录上游服务在子分段中记录的相同调用。在服务图中，这两个服务的节点都包含来自这些服务的分段的计时和错误信息，而它们之间的边缘节点包含来自上游服务的分段的信息。

![\[一个检测的应用程序，该应用程序调用另一个检测的应用程序。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-cw-servicemap-instrumented-edge.png)


这两个视角都非常有用，因为下游服务精确地记录该应用程序开始和结束处理请求的时间，而上游服务记录往返延迟，包括在两个服务之间传输时请求所花费的时间。

## 服务图


X-Ray 使用您的应用程序发送的数据来生成**服务图**。每个向 X-Ray 发送数据的 Amazon 资源在图中都显示为一项服务。**边缘**连接协同工作以服务于请求的服务。边缘将客户端连接到您的应用程序，又将您的应用程序连接到它所使用的下游服务和资源。

**服务名称**  
分段的 `name` 应该与生成该分段的服务的域名或逻辑名称相匹配。但是，并未强制执行此规则。任何拥有 [https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html](https://docs.amazonaws.cn/xray/latest/api/API_PutTraceSegments.html) 权限的应用程序均可发送任何名称的分段。

服务图是一个 JSON 文档，其中包含有关构成您的应用程序的服务和资源的信息。X-Ray 控制台使用服务图来生成可视化形式或*服务地图*。

![\[跟踪地图\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-simplified.png)


对于分布式应用程序，X-Ray 将处理具有相同跟踪 ID 的请求的服务的节点组合成一个服务图。请求命中的第一个服务会添加一个[跟踪标头](#xray-concepts-tracingheader)，该跟踪标头在前端及其所调用的服务之间传播。

例如，[Scorekeep](xray-scorekeep.md) 运行一个调用微服务（Amazon Lambda 函数）的 Web API，通过使用 Node.js 库来生成随机名称。X-Ray SDK for Java 生成跟踪 ID 并将其包含在对 Lambda 的调用中。Lambda 发送跟踪数据并将跟踪 ID 传递给函数。X-Ray SDK for Node.js 还使用跟踪 ID 发送数据。结果，API、Lambda 服务和 Lambda 函数的节点在跟踪地图上全都显示为看似分离其实连接的节点。

服务图数据的保留期为 30 天。

## 跟踪


**跟踪 ID** 可跟踪请求通过您的应用程序的路径。跟踪会收集单个请求生成的所有分段。该请求通常是一个 HTTP GET 或 POST 请求，它经过负载均衡器，命中您的应用程序代码，生成对其他 Amazon 服务或外部 Web API 的下游调用。HTTP 请求与之交互的第一个受支持服务将向请求中添加一个跟踪 ID 标头，并向下游传播该标头以跟踪延迟、处置和其他请求数据。

![\[跟踪的时间线视图，用于收集单个请求生成的所有分段\]](http://docs.amazonaws.cn/xray/latest/devguide/images/xray-trace-details-cw.png)


请参阅 [Amazon X-Ray 定价](https://www.amazonaws.cn/xray/pricing/)，了解 X-Ray 跟踪的计费方式。跟踪数据保留 30 天。

## 采样


为确保高效跟踪并为应用程序所服务的请求提供代表性样本，X-Ray SDK 应用**采样**算法来确定跟踪哪些请求。默认情况下，X-Ray 开发工具包每秒记录第一个请求，以及任何其他请求的百分之五。

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

例如，您可能希望禁用采样，并跟踪对修改状态或处理用户或交易的调用的所有请求。对于量非常大的只读调用，例如后台轮询、运行状况检查或连接维护，您采用较低的采样率仍可获取足够的数据来了解出现的任何问题。

有关更多信息，请参阅 [配置采样规则](xray-console-sampling.md)。

## 跟踪标头


所有请求都被跟踪，直到一个可配置的最低限度。在达到这一最低限度后，只有一部分请求被跟踪，以避免不必要的开销。采样决策和跟踪 ID 添加到名为 ** 的**跟踪标头`X-Amzn-Trace-Id`的 HTTP 请求中。请求命中的第一个 X-Ray 集成服务会添加一个跟踪标头，该跟踪标头由 X-Ray SDK 读取并包含在响应中。

**Example 具有根跟踪 ID 和采样决策的跟踪标头**  

```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
```

**跟踪标头安全性**  
跟踪标头可以源自 X-Ray SDK、Amazon Web Services 服务 服务或客户端请求。应用程序可以从传入请求中删除 `X-Amzn-Trace-Id`，避免由于用户向其请求中添加跟踪 ID 或采样决策而导致出现问题。

如果请求来自检测的应用程序，跟踪标头还可以包含父分段 ID。例如，如果应用程序使用检测的 HTTP 客户端调用下游 HTTP Web API，则 X-Ray SDK 将原始请求的分段 ID 添加到下游请求的跟踪标头中。为下游请求提供服务的检测应用程序，可以记录父分段 ID 以连接两个请求。

**Example 跟踪标头带有根跟踪 ID、父分段 ID 和采样决策**  

```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
```

`Lineage` 可能会附加到 Lambda 和以及作为其处理机制一部分的其他 Amazon Web Services 服务 的跟踪标头，不应直接使用。

**Example 跟踪带有世系的标头**  

```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1;Lineage=25:a87bd80c:1
```

## 筛选条件表达式


即使使用采样，复杂应用程序也会生成大量数据。Amazon X-Ray 控制台提供了易于浏览的服务图视图。它显示运行状况和性能信息，帮助您识别问题和机会，用于优化应用程序。对于高级跟踪，您可以细化以跟踪单个请求，或者使用**筛选表达式**来查找与特定路径或用户相关的跟踪。

![\[深入查看各个请求的跟踪\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-filter-httpurlCONTAINS-cw.png)


## 组


通过扩展筛选条件表达式，X-Ray 也支持组功能。通过使用筛选条件表达式，您可以定义接受跟踪进入组的标准。

您可以按名称或 Amazon 资源名称（ARN）调用组，以生成自己的服务图、跟踪摘要和 Amazon CloudWatch 指标。创建组后，将根据组的筛选条件表达式检查传入跟踪，因为它们存储在 X-Ray 服务中。匹配每个标准的跟踪数量的指标每分钟都会发布到 CloudWatch。

更新组的筛选条件表达式不会更改已记录的数据。更新仅应用于后续跟踪。这可能会生成新旧表达式的合并图。为避免发生这种情况，请删除当前群组并创建一个新的群组。

**注意**  
群组按检索到的符合筛选条件表达式的追踪数量计费。有关更多信息，请参阅[Amazon X-Ray定价](https://www.amazonaws.cn/xray/pricing/)。

有关组的更多信息，请参阅 [配置组](xray-console-groups.md)。

## 注释和元数据


当您检测应用程序时，X-Ray SDK 记录有关传入和传出请求、使用的 Amazon 资源和应用程序本身的信息。您可以向分段文档中添加其他信息作为注释和元数据。注释和元数据在跟踪级别汇总，可以添加到任何分段或子分段。

**注释** 是简单的键-值对，经编制索引后用于[筛选条件表达式](xray-console-filters.md)。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) API 时使用的数据。

X-Ray 最多为每个跟踪的 50 条注释编制索引。

**元数据**是具有任何类型值的键-值对，包括对象和列表，但没有编制索引。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的数据。

 您可以在 CloudWatch 控制台的[跟踪详情](xray-console-traces.md#xray-console-traces-view)页中的分段或子分段详情窗口中查看注释和元数据。

![\[可以在 CloudWatch 控制台的分段或子分段详情中查看注释和元数据\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-cw-subsegment-metadata.png)


## 错误、故障和异常


X-Ray 跟踪在您的应用程序代码中发生的错误以及下游服务返回的错误。错误分类如下。
+ **`Error`** - 客户端错误（400 系列错误）
+ **`Fault`** - 服务器故障（500 系列错误）
+ **`Throttle`** - 限制错误（429 请求过多）

如果在您的应用程序为某个检测的请求提供服务时发生异常，X-Ray SDK 会记录有关异常的详细信息，包括堆栈跟踪（如果可用）。您可以在 X-Ray 控制台的[分段详细信息](xray-console-traces.md#xray-console-segments)下方查看异常。