Ongrid 内置可观测性栈揭秘:Prometheus + Loki + Tempo + Grafana 自动接线是怎么做到的
Ongrid 内置可观测性栈揭秘:Prometheus + Loki + Tempo + Grafana 自动接线是怎么做到的
Ongrid 是一款开源运维 AI Agent,它内置了一套完整的可观测性栈:Prometheus 管指标、Loki 管日志、Tempo 管链路、Grafana 管可视化,并且能自动完成数据源接线和仪表盘推送——装完即用,无需手动配置。本文带你拆解这套"自动接线"背后的实现原理。
一句话讲清楚:四条数据线,一个统一视图
传统部署 Prometheus + Loki + Tempo + Grafana 至少要折腾几十个配置文件。Ongrid 的思路是:每个组件只干一件事,接线工作交给 ongrid manager 自动完成。
四个角色分工如下:
| 组件 | 职责 | 版本 | 默认保留期 |
|---|---|---|---|
| Prometheus | 指标存储 + AI Agent 的 PromQL 查询后端 | v2.54.0 | 90 天 / 20GB |
| Loki | 单二进制日志后端,支持 OTLP 日志 | 3.4.0 | 30 天(720h) |
| Tempo | 单二进制链路(Trace)后端,OTLP 接收 | 2.10.0 | 7 天(168h) |
| Grafana | 可视化,数据源与仪表盘由 ongrid 自动同步 | 11.1.4 | — |
服务编排定义在 deploy/docker-compose.yml(本地开发)和 deploy/install/docker-compose.yml(生产安装包),两者的组件完全一致,只是生产版把所有端口收进了 Docker 内部网络。
关键设计一:数据不是"拉"的,是"推"的
这是 ongrid 可观测性栈区别于普通 Prometheus 部署的地方:边缘主机的指标、日志、链路全部主动推送到云端,而不是让 Prometheus 去抓(scrape)。
edge agent ──tunnel 隧道──▶ ongrid manager ──remote_write──▶ Prometheus
│
└──OTLP──▶ nginx(鉴权网关)──▶ Loki / Tempo
- 指标:边缘 agent 采到主机/进程指标后,通过隧道 RPC 推给 manager,manager 再以
remote_write写入 Prometheus。所以 Prometheus 容器里专门开了--web.enable-remote-write-receiver参数(见 deploy/docker-compose.yml)。 - 日志:边缘的 otelcol-contrib 直接走 nginx 的
/loki/api/v1/push和 OTLP 接口推入 Loki,manager 的 Go 进程不在这条字节流上,不占内存。 - 链路:Trace 走 nginx
/v1/traces进 Tempo。
这套"边缘主动推"的设计写得很明确:云端 Prometheus 根本连不到你家里/内网边缘机器,scrape 模式天然走不通,推模式才是唯一解。
nginx 是数据面的统一鉴权门
所有边缘遥测入口都在 deploy/install/nginx.conf 里做了 auth_request 二次鉴权:
/loki/api/v1/push、/loki/otlp/v1/logs→ 校验后转发到loki:3100/v1/traces→ 校验后转发到tempo/prometheus/→ 校验后转发到 Prometheus UI
校验通过后 nginx 会把 x_edge_id 注入请求头,这样每条日志、每条 span 天然带上"来自哪台机器"的身份。Loki 的配置里也对应把这些属性索引进标签(见 deploy/install/loki-config.yaml),查询时按 device_id、service.name 过滤一目了然。
关键设计二:Tempo 反向"喂"给 Prometheus
这是最容易忽略的一条暗线:Trace 数据会反过来生成指标。
看 deploy/install/tempo-config.yaml 的 metrics_generator 配置:
- Tempo 内置 span-metrics 生成器,从每条 span 提取出
traces_spanmetrics_calls_total(调用量/错误率/耗时 RED 指标),通过remote_write写回同一个 Prometheus; - 同时 service-graphs 生成器产出服务间调用关系,喂给前端的服务拓扑图。
好处是:AI Agent 做根因分析时,只需查一套 PromQL,指标、错误率、链路派生数据全在 Prometheus 里。而 Grafana 侧的 Tempo 数据源则把这条链路的 UI 打通了——在 trace 详情里点一下就能跳到对应日志(tracesToLogsV2 按 service.name、edge_id 自动对齐标签,见 deploy/install/grafana/provisioning/datasources/tempo.yml)。
关键设计三:Grafana 接线全自动,三步完成
很多团队卡在"Prometheus 有了、数据也有了,Grafana 还要配数据源、传仪表盘 JSON"。Ongrid 的 manager 把这三步全包了,核心实现在 internal/manager/biz/grafana/service.go:
第 1 步:首启动自动创建 Service Account
manager 启动时会调用 BootstrapEmbedded(main.go 中的启动钩子):用安装时生成的 Grafana 管理员账号调 /api/serviceaccounts,自动创建一个名为 ongrid 的 Service Account 并签发 token,token 存进系统设置表。之后所有对 Grafana 的操作都用这个 token,运维人员不需要登录 Grafana 配任何东西。
第 2 步:数据源 upsert,永不重复
Sync 方法会按固定 UID(ongrid-prometheus、ongrid-loki、ongrid-tempo、ongrid-elasticsearch)做 upsert:
- 重复执行只会覆盖更新,不会产生一堆重复数据源;
- Prometheus 的 URL 直接读自
prom.query_url设置——保证 manager 写数据和 Grafana 查数据指向同一个 TSDB; - 内置 Loki 换成外部 Loki/Elasticsearch 时,
SyncLogsDatasource只更新对应的那一个数据源,不动仪表盘。
第 3 步:仪表盘随二进制内嵌推送
manager 二进制里用 go:embed 内嵌了 dashboard JSON(internal/manager/biz/grafana/dashboards/),每次 Sync 都会全量推到 Grafana 的 ongrid 文件夹。安装包里另外预置了三个开箱仪表盘:服务器详情、集群总览、manager 自身运行(deploy/install/grafana/provisioning/dashboards/)。
还有一个更"卷"的细节:你在 ongrid 监控页面自定义的面板(CPU、内存、Top 8 进程、磁盘 IO 等 PromQL 面板),manager 会把它们实时镜像成一张 ongrid-monitor 仪表盘推给 Grafana——保证"在 Grafana 中打开"看到的和 ongrid 页面完全一致(见 SyncMonitorPanels,service.go#L590-L617)。
关键设计四:可观测性栈反过来喂 AI Agent
这套栈最终服务的对象不是人,是 AIOps Agent。
- manager 内置
query_promql工具,AI 直接对http://prometheus:9090/prometheus发起查询——这就是为什么 Prometheus 在生产 compose 里是"核心服务"且不对外发布端口,只在容器网络内被 manager 访问; - 告警评估器(alert evaluator)同样复用这套 Prom 查询路径,Trace 派生的延迟/错误率指标让"慢请求告警"能直接落到具体服务;
- 日志侧,AI 通过 Loki 按
edge_id/service.name拉取错误上下文,与指标、Trace 交叉印证。
换句话说:指标 → 发现异常,Trace → 定位服务,日志 → 还原现场,三条数据线在 AI 的推理链上闭环。
生产部署速查:这些细节别踩坑
如果你要自己部署 ongrid,以下是这套可观测性栈的几个关键约束(来源:deploy/README.md 与安装 compose):
- 生产环境 Prometheus 不发布端口:只能在机器内验证,例如
docker exec ongrid-prometheus wget -qO- http://localhost:9090/-/ready; - Grafana 通过 nginx 暴露在
https://<host>/grafana/,与主站共用同一套会话鉴权,Grafana 自身配置了匿名只读(Editor 角色)供 ongrid 页面 drilldown 内嵌使用; - 所有状态都落在
/var/lib/ongrid/<服务>主机目录(prometheus、loki、tempo、grafana 各自独立),方便备份、迁移到快盘或 NFS——这是刻意不用 named volume 的取舍; - 保留期可调:
ONGRID_PROM_RETENTION_TIME(默认 2160h)、ONGRID_LOKI_RETENTION_PERIOD(默认 720h)、ONGRID_TEMPO_BLOCK_RETENTION(默认 168h)都支持环境变量覆盖; - manager 自身也被监控:deploy/install/prometheus-rules.yml 内置了一组
source="self"的自观测告警规则(manager 宕机、LLM 错误率、DB 连接池打满、告警评估器卡死等),修改后curl /prometheus/-/reload热加载即可。
小结
Ongrid 的可观测性栈之所以"自动接线",本质是四件事:
- 推模式采集——边缘 agent 把指标/日志/Trace 推过 nginx 鉴权网关,云端零可达性问题;
- Tempo 反哺 Prometheus——spanmetrics 生成器让 AI 只用 PromQL 一套查询语言;
- Grafana 全自动运维——SA token 自举 + 固定 UID upsert 数据源 + 内嵌仪表盘推送;
- 数据服务于 AI——Prometheus 不对外,专供 Agent 的
query_promql工具和告警评估器消费。
想深入看设计动机,可以读 ADR 文档:ADR-033 应用性能监控 和 HLD-001 日志管道设计。装完 ongrid 之后打开监控页,数据已经在流动了。


