Skip to main content
以下指南假定你已按照all-in-one 镜像说明或仅本地模式中的说明部署了开源 ClickStack，并完成初始用户创建。或者，你也可以跳过所有本地设置，直接连接到我们的 ClickStack 托管演示 play-clickstack.clickhouse.com，它使用的正是这个数据集。 本指南使用托管在公共 ClickHouse playground 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) 。

​
演示架构

该演示由使用不同编程语言编写的微服务组成，这些微服务通过 gRPC 和 HTTP 相互通信，此外还有一个使用 Locust 模拟用户流量的负载生成器。此演示的原始源代码已修改为使用 ClickStack 插桩。
架构
鸣谢：https://opentelemetry.io/docs/demo/architecture/ 有关该演示的更多详细信息，请参见：

​
演示步骤

我们已使用 ClickStack SDKs 为此演示完成了插桩，并将这些服务部署在 Kubernetes 中，同时还采集了它们的指标和日志。
1

连接到演示服务器

仅限本地模式如果你在以本地模式部署时点击了 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: 留空
2

修改数据源

仅限本地模式如果你在以 Local Mode 部署时点击了 Connect to Demo Server，则可以跳过此步骤。使用此模式时，数据源会带有 Demo_ 前缀，例如 Demo_Logs
向上滚动到 Sources，将各个数据源——Logs、Traces、Metrics 和 Sessions——修改为使用 otel_v2 数据库。
你可能需要重新加载页面，以确保每个数据源中都列出了完整的数据库列表。
3

调整时间范围

将时间调整为通过右上角的时间选择器显示过去 1 day 的所有数据。你可能会注意到概览柱状图中的错误数量有细微变化，若干连续的柱子中红色部分会略有增加。
柱子的位置会因你查询数据集的时间不同而有所变化。
4

筛选出错误

如需突出显示错误，请使用 SeverityText 过滤器并选择 error，这样只会显示错误级别的条目。这样一来，错误会更加明显：
5

识别错误模式

借助 HyperDX 的聚类功能，您可以自动识别错误，并将其归纳为有意义的模式。在处理大量日志和链路追踪时，这能加快分析效率。要使用此功能，请在左侧面板的 分析模式 菜单中选择 Event Patterns。这些错误聚类揭示了与支付失败相关的问题，其中包括一个名为 Failed to place order 的模式。其他聚类还表明存在银行卡扣费问题以及缓存已满的情况。请注意，这些错误聚类很可能来自不同的服务。
6

查看错误模式

点击与我们报告的问题“用户能够完成支付”最明显相关的错误集群：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.
7

在 Explore 中浏览基础设施

我们已经发现了一个与缓存相关的错误，它很可能是导致支付失败的原因。我们仍需确定这个问题在微服务架构中的具体来源。考虑到这个缓存问题，接下来检查底层基础设施是合理的——相关的 Pod (容器组) 是否可能存在内存问题？在 ClickStack 中，日志和指标是统一的，并会结合上下文显示，这让我们能更快定位根本原因。选择 Infrastructure 选项卡，查看 frontend 服务底层 Pod (容器组) 的相关指标，并将时间范围扩展到 1d：这个问题看起来不像与基础设施有关——在这段时间内，无论错误发生前还是发生后，指标都没有明显变化。关闭基础设施选项卡。
8

查看一条 trace

在 ClickStack 中，链路追踪也会自动与日志和指标关联。让我们查看与所选日志关联的 trace，以确定是哪个服务导致了问题。选择 Trace 以可视化相关的 trace。向下滚动该视图，我们可以看到 HyperDX 如何将跨多个微服务的分布式 trace 可视化，并连接各个服务中的 span。一次支付显然会涉及多个微服务，包括执行结账和货币转换的服务。继续滚动到视图底部后，我们可以看到是 payment 服务引发了该错误，并且该错误会沿着调用链逐级向上传播。
9

搜索链路追踪数据

我们已确认，用户因支付服务中的缓存问题而无法完成购买。让我们更详细地查看该服务的链路追踪，看看能否进一步找出根本原因。选择 搜索，切换到主搜索视图。将数据源切换为 Traces，然后选择 结果表 视图。确保时间范围仍设置为最近一天。此视图显示最近一天内的所有链路追踪。我们知道问题出在支付服务，因此请在 ServiceName 上应用 payment 过滤器。如果选择 Event Patterns，对这些链路追踪应用事件聚类，我们就能立刻看到 payment 服务中的缓存问题。
10

在 Explore 中查看 trace 关联的基础设施

点击 结果表 切换到结果视图。使用 StatusCode 过滤器并将值设为 Error，筛选出错误。选择一条 Error: Visa cache full: cannot add new item. 错误，切换到 Infrastructure 选项卡，并将时间范围扩展到 1d。通过将链路追踪与指标关联起来，我们可以看到，payment 服务的内存和 CPU 先是上升，随后又降到 0 (这可以归因于 pod (容器组) 重启) ——这表明缓存问题引发了资源方面的问题。可以预期，这已经影响了支付完成时间。
11

借助 Event deltas 更快排查问题

Event Deltas 通过将性能或错误率的变化归因于特定数据子集来帮助发现异常，从而更容易快速定位根本原因。虽然我们知道 payment 服务存在缓存问题，导致资源消耗增加，但还没有完全找出根本原因。返回结果表视图，并选择包含这些错误的时间段以缩小数据范围。请确保选择错误出现前左侧的数小时，以及在可能的情况下也包含错误出现后的时间 (该问题可能仍在持续) ：移除错误过滤器，然后从左侧的 分析模式 菜单中选择 Event Deltas。顶部面板显示的是耗时分布，颜色表示事件密度 (span 数量) 。位于主要集中区域之外的那部分事件，通常就是值得进一步调查的对象。如果我们选择耗时大于 1ms 的事件，并应用 Filter by selection 过滤器，就可以分析“正常”事件与耗时约为 0ms 的高密度 span 组之间的差异：在针对这部分数据子集完成分析后，我们可以看到，选择范围之外的“background” spans 大多是 Visa 事务，并且由于缓存错误而产生了 0ms 的响应。
12

借助图表获取更多上下文

在 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 返回。
13

查看指标的更多上下文信息

最后，让我们把缓存大小绘制成一个指标，看看它随时间的变化，从而获得更多上下文信息。填写以下配置值：
  • Data Source: Metrics
  • Metric: Maximum
  • SQL Column: visa_validation_cache.size (gauge) (只需输入 cache 即可自动补全)
  • Where: ServiceName: payment
  • Group By: <empty>
我们可以看到，缓存大小在 4–5 小时内持续增长 (很可能是在一次软件部署之后) ，随后达到 100,000 的最大值。通过 Sample Matched Events，我们可以看到这些错误与缓存达到该上限存在关联；此后，记录显示其大小为 0，同时响应也在 0s 内返回。总之，通过依次分析日志、链路追踪，最后再看指标，我们得出以下结论：
  • 问题出在支付服务
  • 服务行为的变化 (很可能由一次部署引起) 导致 Visa 缓存在 4–5 小时内缓慢增长，最终达到 100,000 的最大值
  • 随着缓存不断增大，资源消耗也随之上升——很可能是由于实现不佳
  • 随着缓存增长，Visa 支付的性能逐渐下降
  • 当达到最大值后，缓存开始拒绝支付，并将自身大小报告为 0。
14

使用会话

会话让我们能够回放用户体验，以可视化方式还原错误是如何从用户视角发生的。虽然它通常不直接用于诊断根本原因，但对于核实客户支持报告的问题很有价值，也可以作为进一步深入调查的起点。在 HyperDX 中，会话与链路追踪和日志相关联，从而提供对底层原因的完整视图。例如，如果支持团队提供了一位遇到支付问题的用户邮箱 Ronny.Windler@gmail.com，通常从该用户的会话入手，比直接搜索日志或链路追踪更有效。先在左侧菜单中打开 Client Sessions 选项卡，然后确认数据源设置为 Sessions，时间范围设置为 Last 1 day：搜索 SpanAttributes.userEmail: Ronny.Windler，找到该客户的会话。选择该会话后，左侧会显示该客户会话的浏览器事件及关联 spans，右侧则会重新呈现用户的浏览器体验：
15

会话回放

可以通过按下 ▶️ 按钮回放会话。在 Highlighted 和 All Events 之间切换，可以查看不同粒度的 span，其中前者会突出显示关键事件和错误。如果滚动到 spans 的底部，可以看到一个与 /api/checkout 关联的 500 错误。选择这个特定 span 的 ▶️ 按钮后，回放会跳转到该会话中的这一位置，让我们能够确认客户当时的体验——支付似乎就是无法完成，而且界面上没有显示任何错误。选择该 span 后，我们可以确认这是由内部错误引起的。点击 Trace 选项卡并滚动查看相连的 spans 后，我们能够确认该客户确实受到了我们的缓存问题影响。
最后修改于 2026年7月23日