> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 使用 ClickStack 的 Event deltas
> 使用 ClickStack 的 Event deltas 分析 trace 属性分布，并比较异常 spans
export const Image = ({img, alt, size}) => {
return
;
};
Event deltas 将延迟热力图与自动 attribute 分析结合起来，让你无需编写查询，就能看清 trace 数据的形态，并找出慢 span 有何不同。它有三种使用方式：
* **分布模式 (always on)**：当热力图中没有任何选区时，会显示当前 span 集合中每个 attribute 的值分布。适合用来发现占主导地位或异常稀少的值 (基数离群值) 。
* **比较模式**：在热力图上拖出一个矩形，将其中的 spans (Selection) 与其余所有 spans (Background) 进行比较。适合用于定位偏差。
* **迭代式下钻**：点击任意条形即可按该值进行过滤 (或排除) 。热力图会基于过滤后的 span 集合重新渲染，因此你可以不断缩小范围，直到原因一目了然。
在上面的截图中，热力图右侧边缘大约停留在 10 ms，而不是回到整个上午一直维持的 1 ms 基线。性能劣化仍在持续，因此我们是在事件处理中途捕捉到这一现象的。
## 前置条件
Event deltas 需要一个带有耗时表达式的 **trace** 数据源。任何能产生 span 数据、已接入 OpenTelemetry 的服务均可使用。在所有 ClickStack 部署方式中均可用 (Managed、开源、ClickHouse Cloud) 。
## 入门
1. 在 **数据源** 下拉菜单中，选择一个包含链路追踪数据的 source。source 的名称可以任意；关键是它必须配置为 Trace 类型。**Event Deltas** 选项卡仅对这类 source 启用。
2. 在 **分析模式** 部分，点击 **Event Deltas** 选项卡。
Event deltas 是一种独立的分析模式，与 **结果表** 和 **Event Patterns** 并列。切换到该模式后，视图会变为热力图和 attribute 分析网格，但搜索过滤条件和时间范围会保留，你也可以随时切换回来。
## 热力图
热力图在两个维度上展示 span 的分布：
* **X axis**：时间
* **Y axis**：数值，默认为 span 耗时 (毫秒，对数刻度)
颜色强度表示每个桶中的事件数；颜色越亮，表示 span 越多。
你可以直接从热力图中看出各种模式：双峰延迟、特定时刻出现的延迟尖峰、一条始终较慢的 span 带，或者一条随时间逐渐上移的慢速带 (逐步恶化的性能回退) 。要查看某个区域，请在其上点击并拖拽出一个矩形框。该区域会成为你的 **Selection**，并将下方的分析切换为比较模式。
## 分布模式：基数离群值
在热力图上未选中任何区域时，分析面板会为每个属性显示一个条形图，基于所有匹配的 span 计算。图例显示为 **所有 span** (可见于上方的概览截图) 。
属性会按其值的集中程度排序：由少数几个值主导的属性会排在前面；分布均匀、熵较高的属性则会靠后。
当你想了解数据的**基数形态**时，请使用分布模式：
* **高值**：哪些服务、端点、状态码或主机主导了你的 span 集合？这通常会显示出某个租户、版本或路由承载了大部分流量。
* **低值**：那些确实出现但出现频率很低的值。某个仅出现在 `0.5%` span 中的状态码，或某台几乎不出现的主机，可能才是最值得关注的信号。长尾往往是回归问题和异常行为的藏身之处。
可结合搜索栏先缩小范围 (例如，仅查看 error spans、仅查看 client spans，或仅查看某一个端点) ，再查看该子集的分布。
## 比较模式：偏离正常情况之处
在热力图上单击并拖动一个矩形，即可进入比较模式。选中的 spans 会成为 **Selection** (橙色条) ；矩形外的其余部分则成为 **Background** (绿色条) 。随后，每个属性图表都会将这两组数据并排展示，并按差异最大的属性排序，使偏离最明显的属性排在最前面。某个值如果几乎只出现在其中一侧，或在其中一侧完全不存在，那么它很可能就是造成差异的关键因素。
你绘制的矩形形态会改变你所要回答的问题。下面介绍两种常见形态。
### 用例 1：回归前 vs 回归后
当热力图显示延迟随时间线逐渐升高时 (慢带变厚、亮带上移，或某个清晰的拐点将健康时段与退化时段分开) ，从开始上升的拐点拖出一个矩形，一直拉到窗口右边缘。为了让对比更清晰，应将矩形底边放在健康基线上，而不是坐标轴底部：这样就能只圈定退化窗口中那些确实比正常更慢的 span，而不会把恰好落在同一时间范围内、但其实仍然健康的快速 span 也一并带进来。
热力图下方的属性条按差异幅度从大到小排序。在这个示例中，顶行图表呈现出最强的信号：`SpanKind`、`SpanName` 和 `ScopeName` 都显示出明显的橙绿分化，对应较慢的 Selection 和健康的 Background。结合来看，它们勾勒出了拐点处究竟发生了什么变化。
当你想问“发生了什么变化？”时，这就是合适的形态。还有一种更紧凑的变体，流程相同：当一小团慢速 span 出现在原本平静的带状区域中时 (例如右边缘的短暂突发，或稳定时段中间的一簇) ，就只围绕那一簇画一个小框。形态不同，问题也随之变化：竖向长条是在问 *时间上发生了什么变化*；而聚焦的小框是在问 *这个簇有什么特别之处*。
### 用例 2：慢与快
当热力图在耗时轴上清楚地显示出两组明显分离的延迟分布时，拖出一个覆盖整个时间范围、但只框住上方清晰分离带的宽矩形。较慢的那组会成为 Selection；较快的大部分则成为 Background。
将矩形紧紧框住上方带状区域，并让它与下方密集主体之间保留清晰可见的水平间隔。如果矩形画得过松、渗入较快的那组，差异就会被冲淡。
100 s 的上限线本身就很能说明问题：出现在整数值上的恒定水平线，通常就是固定超时的典型特征。如果没有任何 span 属性能清楚地区分这两组数据，这同样是个有用的结果：它说明你应该去看主机层和运行时层面的指标 (GC 暂停、I/O 争用、调度器延迟、冷缓存效应、噪声邻居) ，而不是 span 属性。
当你想问“慢 spans 和快 spans 到底有什么不同？”而不是追查某个特定异常时，这就是合适的形态。出现分歧的属性指向代码路径或输入层面的原因；对比平平则指向系统性原因。
## 迭代式下钻
比较模式和分布模式串联使用时效果最强。点击任意条形，即可打开一个包含三项操作的弹出框：
* **过滤**：仅保留具有该值的 span
* **排除**：移除具有该值的 span
* **复制**：将该值复制到剪贴板
应用过滤或排除后，热力图中的选择会被清除，热力图会基于新的数据集重新渲染，分布模式也会继续针对这个过滤后的集合进行分析。注意观察热力图的变化：成功的过滤会明显去掉慢速带、让双峰分裂收敛，或抹平向上漂移。然后重复这一过程：找出下一个可疑值，进行过滤，查看新的热力图，再查看新的分布。通常经过几轮迭代，就能将回归问题缩小到一两个属性上。
聚合后的 **Other (N)** 桶会折叠低频值，因此不可点击。若要过滤该桶中的某个特定值，请直接使用[搜索栏](/zh/clickstack/features/search)。
当数据集足够小时，切换到 **结果表** 选项卡即可检查单个链路追踪；你设置的过滤条件会保留。
## 自定义热力图
热力图右上角的齿轮图标会打开 **显示设置** 抽屉面板。
| 参数 | 默认值 | 说明 |
| ------ | ---------------- | ----------------------------------------------------------------------- |
| **标度** | 对数 | 对数适合处理跨度较大的延迟范围；线性更适合范围较窄且分布均匀的情况。 |
| **值** | `(Duration)/1e6` | 可使用任意数值表达式：响应大小、错误率，或自定义 span 属性。 |
| **计数** | `count()` | 用于着色的聚合。可切换为 `avg()`, `sum()`, `p95()`, 或 `countDistinct(field)` 这类表达式。 |
点击 **应用** 即可更新热力图；下方的属性分析也会随之更新。
**仪表盘中的热力图**
同一个热力图也可作为[仪表盘卡片](/zh/clickstack/features/dashboards/overview#create-a-tile-heatmap)使用；如果你想在 Event Deltas 下钻流程之外持续监控分布形态随时间的变化，这会很有用。
以下是一些常见的调整默认值的场景：
* 当延迟区间较窄时，**将标度切换为线性** (例如某个服务的 spans 都在 5 到 50 ms 之间) 。对数标度会把垂直空间浪费在没有数据的高值区间。
* **在 Y 轴上绘制耗时之外的其他指标。** 将 **值** 设为 `SpanAttributes.http.response.size`，可帮助你分析缓慢且*体积大*的响应；像 `if(StatusCode = 'Error', 1, 0)` 这样的表达式，则可绘制各个服务随时间变化的错误频率。
* **按计数以外的指标着色。** 将 **计数** 设为 `p95(Duration)` 后，每个分桶都会按尾部延迟着色，而不是按数量着色，从而凸显那些在基于计数的视图中容易被掩盖的少见但高延迟区域。`countDistinct(TraceId)` 则可在单个 trace 产生大量 spans 时，区分 trace 量与 span 量。
## 高效使用技巧
以下做法能显著提升 Event deltas 的使用效果：
* **先过滤到单个服务。** 不同服务之间的延迟差异很大，混在一起会掩盖真正的信号。开始前，先用搜索栏将范围缩小到一个 `ServiceName` (或一个端点) ，这样热力图和分布反映的才是可相互比较的数据总体。
* **选择视觉对比清晰的区间。** 比较模式在 Selection 带与 Background 有明显差异时效果最好，例如从某个容易识别的时刻开始的性能退化区间，或者与主体明显分离的慢尾。与其余数据高度重叠的选择，往往暴露出来的是噪声，而不是真正的偏差。
* **反复执行：过滤、热力图、再过滤。** 单次选择很少能直接定位根因。把第一次比较当作一个假设，对差异最大的值添加过滤器，然后重新查看新的热力图和分布。经过两三轮迭代，通常就能将一次回归缩小到一两个属性。
* **在不做选择时使用分布模式**，适用于暂时还看不出明显对比的情况 (你知道存在问题，但热力图看起来很均匀) 。先应用一个假设性过滤器，比如只看错误 span、只看客户端 span，或只看某一个端点，然后让属性分布先帮你找出影响最大的值，再去绘制任何矩形。
## 故障排查
### Event Deltas 选项卡不可见
只有在选中了带有耗时表达式的 **Trace** 数据源时，**分析模式** 下才会显示 **Event Deltas** 选项卡。请确认你的数据源已配置为 Trace 类型，并且包含带有耗时信息的 span 数据。
### 属性图表显示的结果很少或没有结果
如果样本太小 (少于几十个 span) ，分布结果在统计上可能没有意义。请扩大时间范围或放宽搜索过滤条件。