企业官网建设流程全解析

HydraDB监控与可观测性完整指南：Prometheus指标、Grafana面板与OpenTelemetry

【免费下载链接】hydradbHydraDB - fast graph database on object storage项目地址: https://gitcode.com/gh_mirrors/hyd/hydradb

HydraDB 是一款运行在对象存储上的分布式图数据库（graph database），内置了完整的可观测性体系：Prometheus 指标端点、Grafana 面板和 OpenTelemetry 遥测导出。本指南带你从零搭建 HydraDB 监控，快速掌握 Prometheus 抓取、Grafana 仪表盘与 OpenTelemetry 三大件的正确用法。📊

一、先认识三个端点：监控从哪里来

HydraDB 的每个节点都监听三个端口，其中9090 管理端口就是监控的入口：

graph-node（数据节点）和graph-indexer（索引器）两个角色都暴露相同的两个管理接口：

GET /readyz # 健康/就绪探针 GET /metrics # Prometheus 文本格式指标

💡 验证节点是否健康的最佳实践：不是看端口是否在监听，而是发一次"写-读"往返查询。

二、最快配置方法：三步接入 Prometheus

1. 手动验证指标输出

在节点所在机器上直接抓取：

curl -sS http://127.0.0.1:9090/metrics

能看到graph_前缀的指标名，说明指标导出已就绪。

2. Kubernetes：启用 ServiceMonitor

官方 Helm chart 内置了 Prometheus Operator 集成，只需一个开关：

模板位于 charts/hydradb/templates/servicemonitor.yaml，它会自动选中带graph.usecortex.io/metrics: "true"标签的 Service，抓取metrics端口的/metrics路径。完整取值见 charts/hydradb/values.yaml。

⚠️ 注意：chart 默认启用 NetworkPolicy，监控侧的命名空间需要打上graph.usecortex.io/monitoring-access: "true"标签，否则 Prometheus 的抓取流量会被策略拦截。

3. 抓取告警前的必读项

HydraDB 的时长直方图（duration histogram）单位各不相同（毫秒与纳秒并存）。在搭建延迟仪表盘或告警前，务必确认每个指标的计量单位，避免把"毫秒"当"秒"画出错误的曲线。📈

三、看懂指标：核心分类速查

指标体系由内核统一采集、按角色导出，源码位于 src/core/metrics.rs，时长直方图的实现见 src/core/histogram.rs。常见类别：

• 错误类计数器：按GraphError错误类别逐类计数，每个错误类别一个独立计数器，便于定位是存储错误、查询错误还是路由错误；
• 时长直方图：查询、缓存、编译等关键路径的延迟分布；
• 运行时计数器：连接、缓存命中、一致性模式（causal/strong）等维度。

设计亮点：指标命名表同时服务于 Prometheus（graph_*）与 OpenTelemetry（db.*/hydradb.*）两套词汇，且由编译期宏保证"新增指标必须同时出现在两个导出端"，防止两套数据口径漂移。

四、Grafana 面板：开箱即用的错误分析看板

仓库自带一个 Grafana 仪表盘定义文件：

• 面板文件：grafana/errors.json
• 仪表盘名称：hydradb-query-engine-code

导入方式：Grafana 控制台 → Dashboards → Import → 上传该 JSON 文件即可。它围绕查询引擎错误组织，配合第二节接好的 Prometheus 数据源，可以快速回答"最近一小时哪类错误在涨"。

🧭 搭配建议：导入后先配置数据源变量，再按服务名（hydradb-graph-node/hydradb-graph-indexer）拆分开关，可分别观察数据层与索引层的错误趋势。

五、OpenTelemetry 导出：日志、追踪与指标三通道

HydraDB 的 OTel 能力集中在独立的遥测 crate crates/telemetry/（crate 名hydradb-telemetry），与图查询内核完全解耦——内核只通过tracing门面发事件，遥测 crate 只负责"订阅端"，这让 OTel 成为可选能力。

1. 开启 OTLP 导出

编译时加特性开关：

cargo build --release --features server-runtime,otlp # 数据节点 cargo build --release --features indexer-runtime,otlp # 索引器

配置全部走标准OTEL_*环境变量，无需学习私有写法：

2. 几个默认值，直接影响你的成本

• 头部采样率默认 5%（crates/telemetry/src/config.rs）：只有带"强制保留"理由的追踪（如慢查询）才 100% 保留，其余按 1/20 采样，控制大集群下的 span 量；
• 慢查询阈值默认 1000ms：超过该阈值的读查询会被标记，是错误追踪的第一线索；
• 指标导出间隔默认 60s：与 Prometheus 抓取节奏对齐，降低缓存锁的争抢。

3. 优雅停机与数据不丢

遥测初始化返回一个TelemetryGuard句柄（crates/telemetry/src/lib.rs）：进程退出或显式shutdown()时会冲刷最后批次的 span 与日志。这恰恰是排障最关键的窗口——Pod 重启前最后几秒的日志不会丢失。

4. 字段脱敏与追踪传播

• 脱敏：crates/telemetry/src/redact.rs 维护字段黑名单，敏感字段不会进入任何导出通道；
• 传播：crates/telemetry/src/propagate.rs 支持 W3Ctraceparent跨节点追踪传播；
• 语义约定：属性词汇表定义在 crates/telemetry/src/semconv.rs，并规定哪些属性可以作为指标标签。

🔍 结构化日志里已经包含：查询指纹、访问路径、缓存结果、一致性模式、scope、cell、存储序列号与规划器决策——排障时这些字段就是现成的"事故现场快照"。

六、新手常见坑位清单

七、延伸阅读与源码地图

• 项目总览与端点表：README.md
• 架构与存储/查询/写入一致性设计：architecture.md
• Helm chart 配置指南（TLS、认证、升级）：charts/hydradb/README.md
• 遥测 crate 入口与模块分工：crates/telemetry/src/lib.rs
• 指标采集核心：src/core/metrics.rs
• 时长直方图实现：src/core/histogram.rs

总结：HydraDB 的监控体系分三层递进——用 9090 端口的/metrics接入Prometheus（或经 Helm chart 的 ServiceMonitor 一键接入），导入 grafana/errors.json 得到Grafana错误分析面板，最后开启otlp特性把日志、追踪、指标三路信号推送到OpenTelemetry收集器。三层都遵循同一原则：遥测出问题时自动降级，绝不让监控本身拖垮数据库。

【免费下载链接】hydradbHydraDB - fast graph database on object storage项目地址: https://gitcode.com/gh_mirrors/hyd/hydradb