Skip to main content

Crate nafana

Crate nafana 

Source
Expand description

接口级隔离监控:bulkhead + 超时 + 降级 + Prometheus /metrics 出口。

执行面提供信号量隔离、单请求超时、降级、配置驱动 isolation 和周期请求汇总日志; 观测面提供同源指标出口、集群 Dashboard 与独立单 owner 平台 controller。

三个接入面:

受管 Application 通过 grafana.observability 自动装配出口,不需要业务挂 Router;独立 Axum 可以使用 metrics。observability 提供冻结身份、共享配置、Dashboard 与平台边界。 controller 独立持有平台写权限,业务副本只持有指标数据面凭据。remote write 失联规则只引用 外部平台持续提供的期望实例指标,不维护库存,也不从应用心跳推断实例本应在线。 controller 的配置装配与 Prometheus YAML 编码统一使用 naml。完整编码后复验 owner, 再原子替换受管文件并复验后请求 reload;编码失败不写文件,reload 失败不回滚已经替换的文件。

§有限目录与资源采集

observability::resources 采集当前进程、可见 cgroup 和显式路径、设备及网卡白名单。 缺失、失败、不支持与过期各自表达,采样不在抓取请求中执行,也不改变业务权限。 延迟出现的有限标签目录须预留最坏序列数;空初始样本不能减小承诺,容量不足时拒绝登记。

Modules§

observability
冻结的观测配置、同源指标出口与单 owner 平台调和。

Structs§

Command
一条被 bulkhead、超时和双轨指标保护的命令(= 一个接口端点)。
FallbackContext
交给业务全局降级处理器的稳定请求视图。
IsolationRule
一条隔离模式的参数;#[derive(Deserialize)] 让业务 yml 直接反序列化。
MonitorConflict
同 key 但参数不一致的注册冲突(crate::Command::try_monitor 的错误产物)。
PrometheusMetricSample
一个 nafana 指标 family 与 label 组合的结构化快照。

Enums§

FallbackCause
触发降级的运行时原因。
FallbackDecision
业务全局降级处理器对当前事件的处理决定。
GlobalFallbackInstallError
安装全局降级处理器时可能出现的唯一性错误。
PrometheusMetricValue
nafana registry 的 provider-neutral 当前值。

Traits§

GlobalFallbackHandler
业务手动实现的进程级终态降级扩展点。

Functions§

current_tps
业务作用:读取当前全局 TPS(每秒事务数):所有标了 TPS 的命令窗口请求数(×权重)之和 / 窗口秒数。 给周期请求日志行尾使用的当前 TPS;Prometheus 侧请用 sum(rate(nafana_tps_total[10s]));查询采样与本地秒桶边界不同,二者不保证逐次相等。
dispatch
业务作用:全局中间件:拿请求 path 在 Trie 上匹配,命中 → 按真实路由懒建/复用命令并套 bulkhead + 超时 + 双轨指标;未命中/未初始化 → 直接放行。
global_fallback_installed
查询当前进程是否已经安装全局降级处理器。
init_isolation
业务作用:启动时调用一次:把 yml 的 grafana.isolation 建成 Trie。 规则为空则不初始化 → dispatch 全部放行(= 配置驱动隔离未启用)。
initialize_global_fallback
初始化属性宏自动收集的全局降级处理器。
install_global_fallback
安装进程级全局降级处理器。
metrics
业务作用:/metrics handler:业务把它挂到路由即可被 Prometheus 抓取。 是否鉴权由业务路由层自定(合同 安全边界);本组件不新增独立端口。
metrics_source
业务作用:提供进程唯一的接口指标源,受管 Application 自动登记,独立宿主可显式登记。
render_metrics
业务作用:渲染包含主请求、全局降级与事务权重事实的稳定 Prometheus 文本。
structured_metrics_snapshot
业务作用:直接从 nafana 全局 registry 读取与 Prometheus 出口同源的结构化当前值。

Type Aliases§

FallbackFn
降级 fn 槽类型:无捕获、可多次调用(每个被拒/超时请求各产一个 future),故 Fn + Send + Sync。 由宏生成的 set_reject_fn/set_timeout_fn 注入。

Attribute Macros§

global_fallback
业务作用:把一个同步终态响应函数收集为 nafana 进程级全局降级入口。 属性不接受参数;函数必须同步、恰好接收一个 FallbackContext,并返回任意 IntoResponse。具体参数和返回类型由生成代码交给 Rust 类型系统校验。 # 参数说明 - attr: 属性参数,必须为空。 - item: 被收集的同步终态响应函数。
grafana
业务作用:# #[grafana] —— 给 axum handler 加 bulkhead 隔离 + 超时 + Prometheus 指标