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

使用 ClickStack 和包含日志、会话、链路追踪及指标的示例数据集快速入门

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

托管 ClickStack

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

1. ​

   选择服务

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

2. ​

   前往 ClickStack UI (HyperDX)

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

3. ​

   下载示例数据

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

   示例数据

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

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

4. ​

   加载样本数据

   要加载这些数据，只需将其发送到已部署的 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) ：

   数据加载需要几分钟。请等待加载完成后再继续后续步骤。

5. ​

   查看会话

   假设我们收到报告，称用户在支付商品时遇到了问题。我们可以使用 HyperDX 的会话回放功能查看他们的操作过程。

   从左侧菜单中选择 Client Sessions。

   此视图可让我们查看电商商店的前端会话。在用户结账并尝试完成购买之前，这些会话都会一直显示为 Anonymous。

   请注意，部分带有电子邮件地址的会话还关联了错误，这可能进一步印证了交易失败的报告。

   选择一个失败且关联了电子邮件地址的 trace。随后出现的视图允许我们回放该用户的会话并查看其问题。按下 play 观看该会话。

   回放中可以看到用户浏览站点并将商品加入购物车。你可以直接跳到会话稍后的位置，查看他们尝试完成付款的过程。

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

   用户未能成功下单，但没有明显的报错。滚动到左侧面板底部，这里包含来自用户浏览器的 Network 和 Console 事件。你会注意到，在发起 /api/checkout 调用时抛出了一个 500 错误。

   选择这个 500 错误。无论是 Overview 还是 Column Values，都没有指出问题的来源，只能看出这是一个意外错误，导致了 Internal Error。

6. ​

   查看链路追踪

   导航到 Trace 选项卡，查看完整的分布式 trace。

   向下滚动该 trace，查看错误的根源——checkout 服务的 span。选择 Payment 服务的 span。

   选择 Column Values 选项卡并向下滚动。我们可以看到，问题与缓存已满有关。

   向上滚动并回到 trace 视图后，我们可以看到日志已与该 span 关联，这得益于我们之前的配置。这些日志提供了更多上下文。

   我们已经确认，支付服务中的缓存被占满，导致支付无法完成。

7. ​

   查看日志

   如需进一步了解详情，我们可以返回 Search：

   从数据源中选择 Logs，并为 payment 服务添加过滤条件。

   可以看到，虽然这个问题是最近才出现的，但受影响的支付笔数很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。

8. ​

   图表指标

   虽然代码中显然引入了错误，但我们可以使用指标来确认缓存大小。前往 Chart Explorer 视图。

   选择 Metrics 作为数据源。完成图表构建器配置，绘制 visa_validation_cache.size (Gauge) 的 Maximum，然后点击 play 按钮。可以明显看出，缓存大小在达到最大值之前一直在增长，之后便开始产生错误。

ClickStack 开源版

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

1. ​

   前往 ClickStack UI (HyperDX)

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

2. ​

   复制摄取 API key

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

3. ​

   下载样本数据

   为了在 UI 中填充样本数据，请下载以下文件：

   样本数据

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

   此文件包含来自我们公开的 OpenTelemetry demo 的示例日志、指标和链路追踪数据——这是一个采用微服务架构的简易电商应用。请将此文件复制到您选择的目录中。

4. ​

   加载样本数据

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

   首先，导出上面复制的 API key。

   # 导出 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
   

   这会模拟 OTLP 日志、trace 和指标来源向 OTel collector 发送数据。在生产环境中，这些来源可能是各种语言的客户端，甚至也可能是其他 OTel collector。

   返回 Search 视图后，你应该会看到数据已开始加载 (如果数据没有显示，请将时间范围调整为 Last 1 hour) ：

   数据加载需要几分钟。请等待加载完成后，再继续后续步骤。

5. ​

   查看会话

   假设我们收到报告，称用户在支付商品时遇到了问题。我们可以使用 HyperDX 的会话回放功能查看他们的实际体验。

   从左侧菜单中选择 Client Sessions。

   在此视图中，我们可以看到电商网站前端的会话。在用户结账并尝试完成购买之前，这些会话都会保持为 Anonymous。

   请注意，部分带有电子邮件地址的会话关联了错误，这可能印证了交易失败的报告。

   选择一个失败且关联了电子邮件地址的 trace。随后出现的视图允许我们回放用户的会话并查看他们遇到的问题。按下 play 观看会话。

   回放显示用户浏览网站并将商品加入购物车。你也可以直接跳到会话后面的部分，查看他们尝试完成支付的过程。

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

   用户未能成功下单，而且没有明显的报错。滚动到左侧面板底部，这里包含来自用户浏览器的网络和控制台事件。你会注意到，在调用 /api/checkout 时抛出了一个 500 错误。

   选择这个 500 错误。无论是 Overview 还是 Column Values，都无法看出问题的来源，只能知道这是一个意外错误，导致了 Internal Error。

6. ​

   查看链路追踪

   导航到 Trace 选项卡，查看完整的分布式 trace。

   向下滚动 trace，查看错误的源头——也就是 checkout 服务的 span。选择 Payment 服务的 span。

   选择 Column Values 选项卡并向下滚动。可以看到，问题与缓存已满有关。

   向上滚动并返回 trace 后，可以看到日志已与该 span 关联，这是我们先前配置的结果。这些日志提供了更多上下文。

   我们已经确认，payment 服务中的缓存正在被填满，从而导致支付无法完成。

7. ​

   查看日志

   如需进一步了解详情，我们可以返回 Search 视图：

   从数据源中选择 Logs，并对 payment 服务应用过滤器。

   可以看到，虽然这是最近出现的问题，但受影响的支付数量很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。

8. ​

   图表指标

   虽然代码中显然引入了错误，但我们可以使用指标来确认缓存大小。前往 Chart Explorer 视图。

   选择 Metrics 作为数据源。完成图表构建器中的设置，绘制 visa_validation_cache.size (Gauge) 的 Maximum，然后点击 play 按钮。可以明显看出，缓存大小在达到最大值之前一直在增长，随后便开始出现错误。