qihuaiflow/docs/observability/alloy-bake-plan.md

alloy traces 配置 bake 计划 (Task #952)

必要性判断

• 必要性: 🟡 中等
• 理由: 当前 alloy 配置通过 bind mount 在 /tmp/alloy/config.alloy,在容器重启或宿主机 /tmp 清理时存在配置丢失风险。把配置 bake 进镜像让 alloy 容器自包含,符合容器 immutable 原则。
• 风险: 重建 alloy 镜像 + 重启容器期间,metrics 采集会中断 1-3 分钟,可能影响 Grafana 看板。
• 冲突: 与 P1-2 nginx / P1-1 测试无冲突,可独立执行。

交付物(本会话已完成)

• alloy/Dockerfile:基础 grafana/alloy:latest + COPY config.alloy 到 /etc/alloy/config.alloy + HEALTHCHECK
• alloy/config.alloy:与宿主的 /tmp/alloy/config.alloy 同步(1705 bytes)
• alloy/build.sh:自动 build + tag(产物:qihuaiflow-alloy:verified-{TS})
• alloy/README.md:使用说明 + 回滚指引

实际 bake(待低峰期执行)

1. cd /www/wwwroot/qihuaiflow/alloy && ./build.sh
2. 修改 docker-compose.yml alloy 服务 image + 移除 bind mount
3. docker compose up -d alloy
4. 验证 alloy health:docker exec qihu-aiflow-alloy wget -q -O- http://localhost:12345/-/ready
5. 验证 metrics 还在采集:Grafana → Explore → Prometheus → up 查询

当前 traces 状态(已落地,不依赖本次 bake)

• otelcol.receiver.otlp "default" 监听 4317/4318
• receiver 实现 TraceService proto,应用 OTel SDK 不再 UNIMPLEMENTED
• 故意不接 output 出口(等未来接 Tempo/Loki)
• 已修#876 Grafana 双 Claw 看板(qihuaiflow-dual-claw-876)

不 bake 也能正常工作的原因

• 当前配置 bind mount 自 /tmp/alloy/config.alloy,只要宿主不删,容器每次启动都会拿到
• /tmp 在阿里云 Ubuntu 24.04 宿主上重启不清理(systemd 默认)
• bind mount 在 docker-compose.yml 里声明,容器启动时自动挂载

总结

• 现在做:Dockerfile + config + build.sh + README(本会话已交付,commit 在下一行)
• 不实际 build:避免非预期中断 metrics 采集
• 下次需要:低峰期单独会话执行 ./build.sh + docker-compose 切换