05 ClickStack

学员课程 05 ClickStack 的讲师配套材料。

时间安排

约 15 分钟。遥测数据必须在模块 07 的事故实验之前积累起来，所以在本模块允许的最早时刻就启动 collector，并让它一直运行。

讲解要点

• 托管版 ClickStack 把遥测数据存在 ClickHouse Cloud 里；HyperDX 是托管的 UI。 本地 collector 只负责转发数据。同时展示一条端到端的请求追踪，以及 Log source 里一条 新鲜的 DEBUG ... ClickHouse query ok 记录。
• 让学员在步骤 1 先启动 collector，再在步骤 2 启动托管版 ClickStack。这样遥测数据有时间到达， 第一次打开托管 UI 时才看得到有用的内容。
• 在投影仪上展示一条端到端的请求追踪。

常见故障

• OTLP 主机端口 4317/4318 已被占用：让他们在 .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； 后端是在容器网络内访问 collector 的，所以改端口是安全的。
• 没有启动 collector 叠加层（忘了第二个 -f docker-compose.otel.yml），所以 HyperDX 里什么都没有。
• OTLP_AUTH_TOKEN 不匹配，或 .env.workshop 里缺少 CLICKHOUSE_*（collector 会复用 CLICKHOUSE_HOST/PORT/USER/PASSWORD 来访问 Cloud 服务）。
• 还没有产生任何流量；让他们把两个仪表板都点一遍。
• 在 Docker Desktop 上，可选的 --profile container-logs 抓取器无法挂载主机日志路径 （守护进程在虚拟机里）；这是预期行为。后端日志仍然通过 OTLP 传输。 如果 HyperDX 是空的，只用 docker compose ... logs 来诊断转发器本身。
• 叠加层重建后端之后，应用以前会返回 502（前端 nginx 缓存了旧的后端 IP）。前端现在每个请求都会 重新解析，所以它会在约 10 秒内自愈，不需要手动重启。已在预演中确认修复。
• 预演参考数据：遥测链路端到端验证通过，nyc-taxi-backend 的追踪带有 clickhouse.query 子 span，其中包含 db.statement / db.elapsed_ms / db.rows_returned。已在 2026-07 的净室预演中确认。

重置步骤

• 用两个 compose 文件一起重启： docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build。
• 在 Cloud 控制台里打开服务，选择 ClickStack，如果 SSO 会话过期就重新启动托管 UI。