> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 远程演示数据集
> 通过远程演示数据集开始使用 ClickStack
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
**以下指南假定你已按照[all-in-one 镜像说明](/docs/zh/clickstack/getting-started/oss)或[仅本地模式](/docs/zh/clickstack/deployment/local-mode-only)中的说明部署了开源 ClickStack，并完成初始用户创建。或者，你也可以跳过所有本地设置，直接连接到我们的 ClickStack 托管演示 [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)，它使用的正是这个数据集。**
本指南使用托管在公共 ClickHouse playground [sql.clickhouse.com](https://sql.clickhouse.com) 上的样本数据集，你可以从本地部署的 ClickStack 连接到它。
**托管 ClickStack 不支持**
使用托管 ClickStack 时不支持远程数据库，因此也不支持此数据集。
它包含大约 40 小时的数据，这些数据采集自官方 OpenTelemetry (OTel) Demo 的 ClickHouse 版本。数据会在每晚重新回放，并将时间戳调整到当前时间窗口，以便用户通过 HyperDX 集成的日志、链路追踪和指标来探索系统行为。
**数据差异**
由于该数据集每天都会从午夜开始重新回放，具体的可视化内容可能会因你查看演示的时间不同而有所差异。
## 演示场景
在本次演示中，我们将调查一起发生在某电商网站上的事件，该网站销售望远镜及相关配件。
客户支持团队反馈，用户在结账时无法顺利完成支付。该问题已升级并移交给 Site Reliability Engineering (SRE) 团队进行调查。
SRE 团队将使用 HyperDX 分析日志、链路追踪和指标，以诊断并解决该问题，然后再查看会话数据，以确认他们的结论是否与实际用户行为一致。
## OpenTelemetry Demo
此演示使用的是由 ClickStack 维护的官方 OpenTelemetry Demo 的一个分支版本 (见 [ClickStack maintained fork](https://github.com/ClickHouse/opentelemetry-demo)) 。
### 演示架构
该演示由使用不同编程语言编写的微服务组成，这些微服务通过 gRPC 和 HTTP 相互通信，此外还有一个使用 Locust 模拟用户流量的负载生成器。此演示的原始源代码已修改为使用 [ClickStack 插桩](/docs/zh/clickstack/ingesting-data/sdks/index)。
*鸣谢：[https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
有关该演示的更多详细信息，请参见：
* [OpenTelemetry 文档](https://opentelemetry.io/docs/demo/)
* [由 ClickStack 维护的分支](https://github.com/ClickHouse/opentelemetry-demo)
## 演示步骤
**我们已使用 [ClickStack SDKs](/docs/zh/clickstack/ingesting-data/sdks/index) 为此演示完成了插桩，并将这些服务部署在 Kubernetes 中，同时还采集了它们的指标和日志。**
**仅限本地模式**
如果你在以本地模式部署时点击了 `Connect to Demo Server`，则可以跳过此步骤。使用此模式时，数据源名称会带有 `Demo_` 前缀，例如 `Demo_Logs`
前往 `Team Settings`，然后在 `Local Connection` 旁点击 `Edit`：
将连接重命名为 `Demo`，然后在后续表单中填入以下演示服务器的连接信息：
* `Connection Name`: `Demo`
* `Host`: `https://sql-clickhouse.clickhouse.com`
* `Username`: `otel_demo`
* `Password`: 留空
**仅限本地模式**
如果你在以 Local Mode 部署时点击了 `Connect to Demo Server`，则可以跳过此步骤。使用此模式时，数据源会带有 `Demo_` 前缀，例如 `Demo_Logs`
向上滚动到 `Sources`，将各个数据源——`Logs`、`Traces`、`Metrics` 和 `Sessions`——修改为使用 `otel_v2` 数据库。
你可能需要重新加载页面，以确保每个数据源中都列出了完整的数据库列表。
将时间调整为通过右上角的时间选择器显示过去 `1 day` 的所有数据。
你可能会注意到概览柱状图中的错误数量有细微变化，若干连续的柱子中红色部分会略有增加。
柱子的位置会因你查询数据集的时间不同而有所变化。
如需突出显示错误，请使用 `SeverityText` 过滤器并选择 `error`，这样只会显示错误级别的条目。
这样一来，错误会更加明显：
借助 HyperDX 的聚类功能，您可以自动识别错误，并将其归纳为有意义的模式。在处理大量日志和链路追踪时，这能加快分析效率。要使用此功能，请在左侧面板的 `分析模式` 菜单中选择 `Event Patterns`。
这些错误聚类揭示了与支付失败相关的问题，其中包括一个名为 `Failed to place order` 的模式。其他聚类还表明存在银行卡扣费问题以及缓存已满的情况。
请注意，这些错误聚类很可能来自不同的服务。
点击与我们报告的问题“用户能够完成支付”最明显相关的错误集群：`Failed to place order`。
这将显示与 `frontend` 服务相关的该错误的所有发生记录列表：
选择其中任意一条错误记录。系统会详细显示日志元数据。查看 `Overview` 和 `Column Values` 后，可以看出由于缓存问题，银行卡扣费出现了异常：
`failed to charge card: could not charge the card: rpc error: code = Unknown desc = Visa cache full: cannot add new item.`
我们已经发现了一个与缓存相关的错误，它很可能是导致支付失败的原因。我们仍需确定这个问题在微服务架构中的具体来源。
考虑到这个缓存问题，接下来检查底层基础设施是合理的——相关的 Pod (容器组) 是否可能存在内存问题？在 ClickStack 中，日志和指标是统一的，并会结合上下文显示，这让我们能更快定位根本原因。
选择 `Infrastructure` 选项卡，查看 `frontend` 服务底层 Pod (容器组) 的相关指标，并将时间范围扩展到 `1d`：
这个问题看起来不像与基础设施有关——在这段时间内，无论错误发生前还是发生后，指标都没有明显变化。关闭基础设施选项卡。
在 ClickStack 中，链路追踪也会自动与日志和指标关联。让我们查看与所选日志关联的 trace，以确定是哪个服务导致了问题。
选择 `Trace` 以可视化相关的 trace。向下滚动该视图，我们可以看到 HyperDX 如何将跨多个微服务的分布式 trace 可视化，并连接各个服务中的 span。一次支付显然会涉及多个微服务，包括执行结账和货币转换的服务。
继续滚动到视图底部后，我们可以看到是 `payment` 服务引发了该错误，并且该错误会沿着调用链逐级向上传播。
我们已确认，用户因支付服务中的缓存问题而无法完成购买。让我们更详细地查看该服务的链路追踪，看看能否进一步找出根本原因。
选择 `搜索`，切换到主搜索视图。将数据源切换为 `Traces`，然后选择 `结果表` 视图。**确保时间范围仍设置为最近一天。**
此视图显示最近一天内的所有链路追踪。我们知道问题出在支付服务，因此请在 `ServiceName` 上应用 `payment` 过滤器。
如果选择 `Event Patterns`，对这些链路追踪应用事件聚类，我们就能立刻看到 `payment` 服务中的缓存问题。
点击 `结果表` 切换到结果视图。使用 `StatusCode` 过滤器并将值设为 `Error`，筛选出错误。
选择一条 `Error: Visa cache full: cannot add new item.` 错误，切换到 `Infrastructure` 选项卡，并将时间范围扩展到 `1d`。
通过将链路追踪与指标关联起来，我们可以看到，`payment` 服务的内存和 CPU 先是上升，随后又降到 `0` (这可以归因于 pod (容器组) 重启) ——这表明缓存问题引发了资源方面的问题。可以预期，这已经影响了支付完成时间。
Event Deltas 通过将性能或错误率的变化归因于特定数据子集来帮助发现异常，从而更容易快速定位根本原因。
虽然我们知道 `payment` 服务存在缓存问题，导致资源消耗增加，但还没有完全找出根本原因。
返回结果表视图，并选择包含这些错误的时间段以缩小数据范围。请确保选择错误出现前左侧的数小时，以及在可能的情况下也包含错误出现后的时间 (该问题可能仍在持续) ：
移除错误过滤器，然后从左侧的 `分析模式` 菜单中选择 `Event Deltas`。
顶部面板显示的是耗时分布，颜色表示事件密度 (span 数量) 。位于主要集中区域之外的那部分事件，通常就是值得进一步调查的对象。
如果我们选择耗时大于 `1ms` 的事件，并应用 `Filter by selection` 过滤器，就可以分析“正常”事件与耗时约为 0ms 的高密度 span 组之间的差异：
在针对这部分数据子集完成分析后，我们可以看到，选择范围之外的“background” spans 大多是 Visa 事务，并且由于缓存错误而产生了 0ms 的响应。
在 ClickStack 中，我们可以将日志、链路追踪或指标中的任何数值绘制成图表，以便获得更充分的上下文。
我们已经确定：
* 问题出在支付服务
* 某个缓存已满
* 这导致资源消耗增加
* 该问题导致 Visa 支付无法完成，或者至少会使其完成时间变得很长。
从左侧菜单中选择 `Chart Explorer`。填写以下配置值，以按图表类型绘制支付完成所需的时间：
* `Data Source`: `Traces`
* `Metric`: `Maximum`
* `SQL Column`: `Duration`
* `Where`: `ServiceName: payment`
* `Timespan`: `Last 1 day`
点击 `▶️` 后，即可看到支付性能如何随时间逐渐恶化。
如果将 `Group By` 设置为 `SpanAttributes['app.payment.card_type']` (只需输入 `card` 即可自动补全) ，我们就能看到与 Mastercard 相比，该服务在 Visa 交易上的性能是如何下降的：
请注意，一旦发生错误，响应会在 `0s` 返回。
最后，让我们把缓存大小绘制成一个指标，看看它随时间的变化，从而获得更多上下文信息。
填写以下配置值：
* `Data Source`: `Metrics`
* `Metric`: `Maximum`
* `SQL Column`: `visa_validation_cache.size (gauge)` (只需输入 `cache` 即可自动补全)
* `Where`: `ServiceName: payment`
* `Group By`: ``
我们可以看到，缓存大小在 4–5 小时内持续增长 (很可能是在一次软件部署之后) ，随后达到 `100,000` 的最大值。通过 `Sample Matched Events`，我们可以看到这些错误与缓存达到该上限存在关联；此后，记录显示其大小为 `0`，同时响应也在 `0s` 内返回。
总之，通过依次分析日志、链路追踪，最后再看指标，我们得出以下结论：
* 问题出在支付服务
* 服务行为的变化 (很可能由一次部署引起) 导致 Visa 缓存在 4–5 小时内缓慢增长，最终达到 `100,000` 的最大值
* 随着缓存不断增大，资源消耗也随之上升——很可能是由于实现不佳
* 随着缓存增长，Visa 支付的性能逐渐下降
* 当达到最大值后，缓存开始拒绝支付，并将自身大小报告为 `0`。
会话让我们能够回放用户体验，以可视化方式还原错误是如何从用户视角发生的。虽然它通常不直接用于诊断根本原因，但对于核实客户支持报告的问题很有价值，也可以作为进一步深入调查的起点。
在 HyperDX 中，会话与链路追踪和日志相关联，从而提供对底层原因的完整视图。
例如，如果支持团队提供了一位遇到支付问题的用户邮箱 `Ronny.Windler@gmail.com`，通常从该用户的会话入手，比直接搜索日志或链路追踪更有效。
先在左侧菜单中打开 `Client Sessions` 选项卡，然后确认数据源设置为 `Sessions`，时间范围设置为 `Last 1 day`：
搜索 `SpanAttributes.userEmail: Ronny.Windler`，找到该客户的会话。选择该会话后，左侧会显示该客户会话的浏览器事件及关联 spans，右侧则会重新呈现用户的浏览器体验：
可以通过按下 ▶️ 按钮回放会话。在 `Highlighted` 和 `All Events` 之间切换，可以查看不同粒度的 span，其中前者会突出显示关键事件和错误。
如果滚动到 spans 的底部，可以看到一个与 `/api/checkout` 关联的 `500` 错误。选择这个特定 span 的 ▶️ 按钮后，回放会跳转到该会话中的这一位置，让我们能够确认客户当时的体验——支付似乎就是无法完成，而且界面上没有显示任何错误。
选择该 span 后，我们可以确认这是由内部错误引起的。点击 `Trace` 选项卡并滚动查看相连的 spans 后，我们能够确认该客户确实受到了我们的缓存问题影响。