示例日志、链路追踪和指标 - ClickHouse Documentation

本指南通过一个示例数据集演示 ClickStack Open Source 和托管 ClickStack。

托管 ClickStack
ClickStack 开源版

以下指南假设您已完成托管 ClickStack 入门指南，并已记录连接凭据。

选择服务

在 ClickHouse Cloud 主页面中，选择“托管 ClickStack”服务。

前往 ClickStack UI (HyperDX)

在左侧菜单中选择 ClickStack，即可进入 ClickStack UI，系统会自动完成身份验证。

下载示例数据

为了让 UI 中显示示例数据，请下载以下文件：示例数据

# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# or
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz

此文件包含来自我们的公开 OpenTelemetry demo 的示例日志、指标和链路追踪——它是一个由微服务构成的简单电商应用。将此文件复制到你选定的目录中。

加载样本数据

要加载这些数据，只需将其发送到已部署的 OpenTelemetry (OTel) collector 的 HTTP 端点即可。运行以下命令，将数据发送到 OTel collector：

for filename in $(tar -tf sample.tar.gz); do
  endpoint="http://localhost:4318/v1/${filename%.json}"
  echo "loading ${filename%.json}"
  tar -xOf sample.tar.gz "$filename" | while read -r line; do
    printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
    -H "Content-Type: application/json" \
    -H "authorization: ${CLICKSTACK_API_KEY}" \
    --data-binary @-
  done
done

这会模拟 OTLP 日志、trace 和指标来源向 OTel collector 发送数据。在生产环境中，这些来源可能是各种语言的客户端，甚至也可能是其他 OTel collector。返回 Search 视图后，你应该会看到数据已开始加载 (如果数据没有显示，请将时间范围调整为 Last 1 hour) ：数据加载需要几分钟。请等待加载完成后，再继续后续步骤。

查看会话

假设我们收到报告，称用户在支付商品时遇到了问题。我们可以使用 HyperDX 的会话回放功能查看他们的操作过程。从左侧菜单中选择 Client Sessions。此视图可让我们查看电商商店的前端会话。在用户结账并尝试完成购买之前，这些会话都会一直显示为 Anonymous。请注意，部分带有电子邮件地址的会话还关联了错误，这可能进一步印证了交易失败的报告。选择一个失败且关联了电子邮件地址的 trace。随后出现的视图允许我们回放该用户的会话并查看其问题。按下 play 观看该会话。回放中可以看到用户浏览站点并将商品加入购物车。你可以直接跳到会话稍后的位置，查看他们尝试完成付款的过程。

所有错误都会以红色标注在时间线上。

用户未能成功下单，但没有明显的报错。滚动到左侧面板底部，这里包含来自用户浏览器的 Network 和 Console 事件。你会注意到，在发起 /api/checkout 调用时抛出了一个 500 错误。选择这个 500 错误。无论是 Overview 还是 Column Values，都没有指出问题的来源，只能看出这是一个意外错误，导致了 Internal Error。

查看链路追踪

导航到 Trace 选项卡，查看完整的分布式 trace。向下滚动 trace，查看错误的源头——也就是 checkout 服务的 span。选择 Payment 服务的 span。选择 Column Values 选项卡并向下滚动。可以看到，问题与缓存已满有关。向上滚动并返回 trace 后，可以看到日志已与该 span 关联，这是我们先前配置的结果。这些日志提供了更多上下文。我们已经确认，payment 服务中的缓存正在被填满，从而导致支付无法完成。

查看日志

如需进一步了解详情，我们可以返回 Search：从数据源中选择 Logs，并为 payment 服务添加过滤条件。可以看到，虽然这个问题是最近才出现的，但受影响的支付笔数很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。

图表指标

虽然代码中显然引入了错误，但我们可以使用指标来确认缓存大小。前往 Chart Explorer 视图。选择 Metrics 作为数据源。完成图表构建器中的设置，绘制 visa_validation_cache.size (Gauge) 的 Maximum，然后点击 play 按钮。可以明显看出，缓存大小在达到最大值之前一直在增长，随后便开始出现错误。

以下示例假设您已按照一体化镜像的使用说明启动了开源 ClickStack，并已连接到本地 ClickHouse 实例。

前往 ClickStack UI (HyperDX)

访问 http://localhost:8080 即可进入 ClickStack UI。

复制摄取 API key

前往 Team Settings，在 API Keys 部分复制 Ingestion API Key。此 API key 可确保通过 OpenTelemetry collector 进行的数据摄取安全。

下载示例数据

为了让 UI 中显示示例数据，请下载以下文件：示例数据

# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# or
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz

此文件包含来自我们的公开 OpenTelemetry demo 的示例日志、指标和链路追踪——它是一个由微服务构成的简单电商应用。将此文件复制到你选定的目录中。

加载样本数据

要加载这些数据，只需将其发送到已部署的 OpenTelemetry (OTel) collector 的 HTTP 端点即可。首先，导出上面复制的 API key。

# export API key
export CLICKSTACK_API_KEY=<YOUR_INGESTION_API_KEY>

运行以下命令，将数据发送到 OTel collector：

for filename in $(tar -tf sample.tar.gz); do
  endpoint="http://localhost:4318/v1/${filename%.json}"
  echo "loading ${filename%.json}"
  tar -xOf sample.tar.gz "$filename" | while read -r line; do
    printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
    -H "Content-Type: application/json" \
    -H "authorization: ${CLICKSTACK_API_KEY}" \
    --data-binary @-
  done
done

查看会话

假设我们收到报告，称用户在支付商品时遇到了问题。我们可以使用 HyperDX 的会话回放功能查看他们的实际体验。从左侧菜单中选择 Client Sessions。在此视图中，我们可以看到电商网站前端的会话。在用户结账并尝试完成购买之前，这些会话都会保持为 Anonymous。请注意，部分带有电子邮件地址的会话关联了错误，这可能印证了交易失败的报告。选择一个失败且关联了电子邮件地址的 trace。随后出现的视图允许我们回放用户的会话并查看他们遇到的问题。按下 play 观看会话。回放显示用户浏览网站并将商品加入购物车。你也可以直接跳到会话后面的部分，查看他们尝试完成支付的过程。

所有错误都会以红色标注在时间轴上。

用户未能成功下单，而且没有明显的报错。滚动到左侧面板底部，这里包含来自用户浏览器的网络和控制台事件。你会注意到，在调用 /api/checkout 时抛出了一个 500 错误。选择这个 500 错误。无论是 Overview 还是 Column Values，都无法看出问题的来源，只能知道这是一个意外错误，导致了 Internal Error。

查看链路追踪

查看日志

如需进一步了解详情，我们可以返回 Search 视图：从数据源中选择 Logs，并对 payment 服务应用过滤器。可以看到，虽然这是最近出现的问题，但受影响的支付数量很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。

图表指标