> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ClickStack - 示例日志、链路追踪和指标
> 使用 ClickStack 和包含日志、会话、链路追踪及指标的示例数据集快速入门
export const Image = ({img, alt, size}) => {
return
;
};
本指南通过一个示例数据集演示 ClickStack Open Source 和托管 ClickStack。
以下指南假设您已完成[托管 ClickStack 入门指南](/zh/clickstack/deployment/managed)，并已[记录连接凭据](/zh/clickstack/getting-started/managed#next-steps)。
### 选择服务
在 ClickHouse Cloud 主页面中，选择“托管 ClickStack”服务。
### 前往 ClickStack UI (HyperDX)
在左侧菜单中选择 `ClickStack`，即可进入 ClickStack UI，系统会自动完成身份验证。
### 下载示例数据
为了让 UI 中显示示例数据，请下载以下文件：
[示例数据](https://storage.googleapis.com/hyperdx/sample.tar.gz)
```shell theme={null}
# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# 或
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz
```
此文件包含来自我们的公开 [OpenTelemetry demo](https://github.com/ClickHouse/opentelemetry-demo) 的示例日志、指标和链路追踪——它是一个由微服务构成的简单电商应用。将此文件复制到你选定的目录中。
### 加载样本数据
要加载这些数据，只需将其发送到已部署的 OpenTelemetry (OTel) collector 的 HTTP 端点即可。
运行以下命令，将数据发送到 OTel collector：
```shell theme={null}
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 关联，这得益于我们之前的配置。这些日志提供了更多上下文。
我们已经确认，支付服务中的缓存被占满，导致支付无法完成。
### 查看日志
如需进一步了解详情，我们可以返回 `Search`：
从数据源中选择 `Logs`，并为 `payment` 服务添加过滤条件。
可以看到，虽然这个问题是最近才出现的，但受影响的支付笔数很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。
### 图表指标
虽然代码中显然引入了错误，但我们可以使用指标来确认缓存大小。前往 `Chart Explorer` 视图。
选择 `Metrics` 作为数据源。完成图表构建器配置，绘制 `visa_validation_cache.size (Gauge)` 的 `Maximum`，然后点击 play 按钮。可以明显看出，缓存大小在达到最大值之前一直在增长，之后便开始产生错误。
以下示例假设您已按照[一体化镜像的使用说明](/zh/clickstack/getting-started/oss)启动了开源 ClickStack，并已连接到[本地 ClickHouse 实例](/zh/clickstack/getting-started/oss#complete-connection-credentials)。
### 前往 ClickStack UI (HyperDX)
访问 [http://localhost:8080](http://localhost:8080) 即可进入 ClickStack UI。
### 复制摄取 API key
前往 [`Team Settings`](http://localhost:8080/team)，在 `API Keys` 部分复制 `Ingestion API Key`。此 API key 可确保通过 OpenTelemetry collector 进行的数据摄取安全。
### 下载样本数据
为了在 UI 中填充样本数据，请下载以下文件：
[样本数据](https://storage.googleapis.com/hyperdx/sample.tar.gz)
```shell theme={null}
# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# 或
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz
```
此文件包含来自我们公开的 [OpenTelemetry demo](https://github.com/ClickHouse/opentelemetry-demo) 的示例日志、指标和链路追踪数据——这是一个采用微服务架构的简易电商应用。请将此文件复制到您选择的目录中。
### 加载样本数据
要加载这些数据，只需将其发送到已部署的 OpenTelemetry (OTel) collector 的 HTTP 端点即可。
首先，导出上面复制的 API key。
```shell theme={null}
# 导出 API key
export CLICKSTACK_API_KEY=
```
运行以下命令，将数据发送到 OTel collector：
```shell theme={null}
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`](http://localhost:8080/sessions?from=1747312320000\&to=1747312920000\&sessionSource=l1324572572)。
在此视图中，我们可以看到电商网站前端的会话。在用户结账并尝试完成购买之前，这些会话都会保持为 Anonymous。
请注意，部分带有电子邮件地址的会话关联了错误，这可能印证了交易失败的报告。
选择一个失败且关联了电子邮件地址的 trace。随后出现的视图允许我们回放用户的会话并查看他们遇到的问题。按下 play 观看会话。
回放显示用户浏览网站并将商品加入购物车。你也可以直接跳到会话后面的部分，查看他们尝试完成支付的过程。
所有错误都会以红色标注在时间轴上。
用户未能成功下单，而且没有明显的报错。滚动到左侧面板底部，这里包含来自用户浏览器的网络和控制台事件。你会注意到，在调用 `/api/checkout` 时抛出了一个 500 错误。
选择这个 `500` 错误。无论是 `Overview` 还是 `Column Values`，都无法看出问题的来源，只能知道这是一个意外错误，导致了 `Internal Error`。
### 查看链路追踪
导航到 `Trace` 选项卡，查看完整的分布式 trace。
向下滚动 trace，查看错误的源头——也就是 `checkout` 服务的 span。选择 `Payment` 服务的 span。
选择 `Column Values` 选项卡并向下滚动。可以看到，问题与缓存已满有关。
向上滚动并返回 trace 后，可以看到日志已与该 span 关联，这是我们先前配置的结果。这些日志提供了更多上下文。
我们已经确认，payment 服务中的缓存正在被填满，从而导致支付无法完成。
### 查看日志
如需进一步了解详情，我们可以返回 [`Search` 视图](http://localhost:8080/search)：
从数据源中选择 `Logs`，并对 `payment` 服务应用过滤器。
可以看到，虽然这是最近出现的问题，但受影响的支付数量很多。此外，似乎是一个与 Visa 支付相关的缓存导致了问题。
### 图表指标
虽然代码中显然引入了错误，但我们可以使用指标来确认缓存大小。前往 `Chart Explorer` 视图。
选择 `Metrics` 作为数据源。完成图表构建器中的设置，绘制 `visa_validation_cache.size (Gauge)` 的 `Maximum`，然后点击 play 按钮。可以明显看出，缓存大小在达到最大值之前一直在增长，随后便开始出现错误。