Expand description
进程级 provider-neutral 指标核心。
§核心价值
MetricHub 是一个进程内唯一的 descriptor catalog、记录 backend 和结构化快照源。领域 crate
(nafana/naweb/nafka)继续拥有自己的静态 family、低基数 label 与记录时机;本 crate 只统一
冲突审计、容量和导出,不重新定义领域指标语义,也不依赖 OpenTelemetry、Prometheus client、
Axum 或 napp。
§运行架构与安全边界
原生记录入口只接受启动期登记且语义一致的 descriptor。受管兼容源通过
MetricHub::register_legacy_source_reserved 在同一临界区提交 descriptor、source 所有权和最坏
exposition series 预算;冲突、溢出或容量不足时三者都不改变。原生 cell 与显式预留共享
MAX_METRIC_SERIES,目录自身的拒绝诊断预先占位,满载时仍能解释拒绝原因。
Prometheus 文本和 OTLP adapter 都读取同一次结构化快照,不各自维护 registry。label 形状、单值
大小、value kind、histogram 结构或基数不满足目录合同时拒绝当前样本,并以固定 source/reason
计数,不把动态 label 内容写进诊断。动态结构化兼容源只使用扣除原生序列与显式预留后的余量,
按 family/label 排序逐个接纳完整样本。仅文本的旧兼容源不在结构化容量保证内。
Modules§
- atomic
- 固定桶与原子采集,供低开销领域 source 复用。 预分配原子计数与固定桶分布;写侧不构造标签,快照侧转换为统一指标值。
Structs§
- Metric
Conflict - descriptor 注册冲突。
- Metric
Descriptor - 一个指标 family 的静态描述。所有字段都是编译期常量,不含动态内容。
- Metric
Family Snapshot - 一个带唯一 descriptor 语义的指标 family 当前快照。
- Metric
Hub - 唯一进程级指标 backend:descriptor catalog(带冲突审计)+ 进程内记录 + 结构化/Prometheus 导出。
- Metric
Sample - 单个指标样本(family + label 组合 + 值)的结构化快照。
Enums§
- Metric
Kind - 指标类型。
- Metric
Source Registration Error - 指标源在启动期登记 descriptor 与最坏序列预算时的失败分类。
- Metric
Value - 指标样本值。
Constants§
- MAX_
METRIC_ SERIES - 进程内原生、结构化兼容源与诊断按 histogram 展开后的公开序列硬上限。
Traits§
- Legacy
Metrics Source - 兼容期桥:旧指标源先实现本 trait,启动期用
descriptors()做全局冲突审计,文本与非文本出口 优先读取snapshot()的同源结构化值;明确返回None的旧源仅在文本抓取时回落到render_prometheus()。迁移完成后弃用。 - Metric
Recorder - 领域 crate 记录指标的入口。
napp持有唯一MetricHub实例并实现本 trait。