05 ClickStack

用一个本地无状态收集器转发遥测数据，启用 Managed ClickStack，并在云托管的 HyperDX 中查看它。

起点

你位于 build-workshop-v1，无需 checkout。预留约 15 分钟。应用已经完成了 OpenTelemetry 埋点；在本模块中你会用收集器 overlay 把它打开。

前置条件：你的 Cloud 服务正在运行（模块 01）。

为什么

要在之后诊断这个应用，你首先得能看见它。ClickStack（ClickHouse 的可观测性栈，以 HyperDX 作为界面）把 OpenTelemetry 的 traces 和 logs 存储在 ClickHouse 中。在本模块中你会打开收集器，这样经过应用的每个请求都会产生你可以查询的遥测数据。

目标

让应用的 traces 和后端查询日志流入 ClickStack，至少有一条端到端的请求 trace，以及一条可见的成功查询记录流。

第 1 步：运行 OpenTelemetry 收集器 overlay

HyperDX、存储和查询算力都保持由 ClickHouse Cloud 托管。这里唯一的本地组件是一个与本地应用并列的无状态 OpenTelemetry 收集器；它只负责转发遥测数据，并不是一套本地的 ClickStack 或 HyperDX 部署。

先检查收集器端口

收集器把 OTLP 发布在宿主机端口 4317 和 4318 上，而这两个端口常常已被占用。如果模块 00 中 ClickHouse_Demos/workshops/build_workshop/app 里的 ./preflight.sh 对它们发出了 WARN，请在启动 overlay 之前，把 .env.workshop 中的 OTEL_GRPC_HOST_PORT 和 OTEL_HTTP_HOST_PORT 设为 preflight 建议的值（例如 24317 / 24318）。后端是在网络内部访问收集器的，所以重映射宿主机端口是安全的。在克隆仓库内的任何位置重新运行 cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh 来确认端口已经空闲。

`.env.workshop` 和 `docker-compose.otel.yml`

这些变量位于 .env.workshop.example 的 ClickStack 可观测性部分；请在你的 .env.workshop 中填写它们：

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

不要把这个文件 source 进你的 shell。下面的 Compose 命令会直接读取它，这样既能让其中的密码和 API 密钥不进入已导出的 shell 变量，也能确保之后对该文件的修改会生效。

现在带着 overlay 启动整套技术栈。这个 overlay 会在后端设置 OTEL_ENABLED=true、添加 otel-collector 服务（clickhouse/clickstack-otel-collector），并用浏览器遥测配置重新构建前端：

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

收集器会复用 .env.workshop 中的 CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD；后端把 OTLP 导出到 http://otel-collector:4318（HTTP/protobuf）。如果还想在 Linux 宿主机上抓取容器的原始 stdout，请加上 --profile container-logs。

第 2 步：在你的服务上启用 Managed ClickStack

本课程在你自己的 ClickHouse Cloud 服务中使用 Managed ClickStack (HyperDX)：收集器把 otel_* 表写入你的服务，而 HyperDX 界面在那里把它们渲染出来。在控制台中启用它：

控制台 - 你的服务 -> ClickStack -> Start Ingestion -> 跳过收集器那一步（应用的收集器在第 1 步中已经在运行）-> Launch ClickStack

这会把你单点登录进 HyperDX。遥测数据已经开始流动了，所以托管界面一打开就能填充内容。

Managed ClickStack：与经典配置的差异

后端使用的是原生 OpenTelemetry，而不是 ClickStack 文档建议的便捷包 hyperdx-opentelemetry。那个包把 opentelemetry-api==1.30.0 硬性钉死，而这与聊天功能使用的 Langfuse v4 SDK 冲突（后者需要 opentelemetry-api>=1.33.1），两者无法共存于同一个环境。ClickStack 收集器摄取的是标准 OTLP，所以原生发行版的行为完全一致；这里只是自行设置了导出器的环境变量。
ClickStack 的遥测数据存放在你服务上的一个单独数据库中（CLICKSTACK_DATABASE=otel），与应用的数据库（CLICKHOUSE_DATABASE=nyc_tlc_data）区分开。
Traces 和后端 Python 日志通过 OTLP 从自动埋点的后端流出。可选的 --profile container-logs 收集器只适用于未埋点的服务，比如行程写入器；它所使用的 Linux Docker 日志路径在 Docker Desktop 上可能不可用。

第 3 步：产生流量并在 ClickStack 中找到它

打开 Ops 看板，保持其默认的 1m 间隔和 5s 自动刷新运行约 30 秒。然后打开 ClickStack：

在 Traces 中，端到端跟踪一个请求（前端 -> 后端 -> ClickHouse）。
在 Logs 中，选择 nyc-taxi-backend 并找到反复出现的 ClickHouse query ok 记录。它们的时间戳应该每次刷新都往前推进。
让严重级别保持有意义：成功的查询是 DEBUG；真正的空闲唤醒重试和失败会显示为 WARNING 或 ERROR。

你应该会看到 HyperDX 中出现一个名为 nyc-taxi-backend 的服务，其中 /api/... 请求显示为 traces，每条 trace 都带有一个子 clickhouse.query span。

HyperDX Search 视图显示 nyc-taxi-backend 的 traces，一个实时列表，包含 GET /api/health 和 POST 的 span，带有时间戳、服务和耗时列

HyperDX 渲染出应用的 traces：nyc-taxi-backend 服务及其 /api/... 请求 span。

如何验证你已完成

HyperDX 中出现了一个名为 nyc-taxi-backend 的服务。
对 /api/... 的请求显示为 traces，每条都带有一个子 clickhouse.query span，其中携带 db.statement、db.elapsed_ms 和 db.rows_returned。
只要 Ops 看板保持打开，Log source 中就会显示新鲜的 DEBUG ... ClickHouse query ok 记录。
你现在还看不到查询错误：一个健康、已导入数据的应用不会触发安全限制，而 4xx 请求根本到不了 ClickHouse。在模块 07 中，注入的故障会让一个出错的 clickhouse.query span （带有 error.category）变得可观测。

小结

现在这个应用是可观测的：traces 和后端查询日志被记录在 ClickHouse 中，并可以在 ClickStack 中探索。可选的 container-logs profile 会在兼容的 Linux 宿主机上额外加入行程写入器的 stdout。这些遥测数据就是接下来 AI SRE 工作的基础。

最终状态

遥测数据正在流入 ClickStack。继续前往 06 AI SRE，让你的 agent 在它之上构建。

起点

为什么

目标