在上一篇文章中，我们深入探讨了 ClickStack 的架构设计与核心价值。我们知道，它凭借 ClickHouse 与 OpenTelemetry 的精妙组合，为可观测性领域带来了成本与效率的双重革新。纸上得来终觉浅，跟随以下步骤，你可以快速在本地运行一个完整的 ClickStack 实例，并导入一些样例数据体验ClickStack在日志、追踪、指标全领域的、高性能且极具性价比的解决方案。

1.搭建测试环境

工欲善其事，必先利其器。为了顺利完成本次实验，请确保你的本地开发环境已安装Docker和Git。

由于是测试环境，我们选择All-in-One的部署模式，单个 Docker 容器，捆绑了所有 ClickStack 组件，用于演示和局部全栈测试。

这个综合的 Docker 镜像捆绑了所有 ClickStack 组件：

• ClickHouse
• HyperDX
• OpenTelemetry (OTel) 收集器（在端口 4317 和 4318 上暴露 OTLP）

此选项包含身份验证，允许在会话和用户之间持久保存仪表板、警报和保存的搜索。

1.1.使用Docker部署

以下命令将运行一个 OpenTelemetry 收集器（在端口 4317 和 4318 上）和 HyperDX 界面（在端口 8080 上）。

1

docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

部署成功后会打印环境信息

1.2.访问HyperDX界面

访问 http://localhost:8080 以访问 HyperDX 界面。

创建一个用户，提供符合要求的用户名和密码。

点击 Create 后，将为集成的 ClickHouse 实例创建数据源。

随后会进入到HyperDX的主界面，此时并没有数据

2.导入示例日志、trace和指标

2.1.配置数据源

All-in-One部署模式中已经部署了Clickhouse，直接配置connection本地Clickhouse

2.2.复制摄取API KEY

导航到 团队设置 并从 API 密钥 部分复制 摄取 API 密钥。此 API 密钥确保通过 OpenTelemetry 收集器进行数据摄取的安全性。

2.3.准备并导入样例数据

1

# wget https://storage.googleapis.com/hyperdx/sample.tar.gz

此文件包含来自我们公共 OpenTelemetry 演示 的示例日志、指标和跟踪——一个简单的微服务电子商务商店。将此文件复制到您选择的目录中。

上面API 密钥导入环境变量，并将数据发送到 OTel 收集器：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# export API key
export CLICKSTACK_API_KEY=<YOUR_INGESTION_API_KEY>

#
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
    echo "$line" | curl -s -o /dev/null -X POST "$endpoint" \
    -H "Content-Type: application/json" \
    -H "authorization: ${CLICKSTACK_API_KEY}" \
    --data-binary @-
  done
done

这模拟了 OLTP 日志、跟踪和指标源将数据发送到 OTel 收集器。在生产环境中，这些源可能是语言客户端，甚至是其他 OTel 收集器。

3.观测日志、trace及指标

3.1.观测日志

在Search视图，默认已经可以观测到日志记录

HyperDX允许您对事件（日志和跟踪）进行全文搜索。您可以通过输入与您的事件匹配的关键字来开始搜索。例如，如果您的日志包含“Error”，您只需在搜索框中输入“Error”即可找到它。

3.2.诊断trace

在trace界面，可以查看完整的分布式跟踪，并诊断问题错误来源

3.3.观测指标

有些时候，我们需要更直观的观测全局错误指标。可以选择相应的指标作为数据源，完成图表构建器以绘制 visa_validation_cache.size (Gauge) 的 最大值 并按播放按钮。缓存显然在达到最大大小之前不断增加，之后生成了错误。