Expand description
接口级隔离监控:bulkhead + 超时 + 降级 + Prometheus /metrics 出口。
执行面提供信号量隔离、单请求超时、降级、配置驱动 isolation 和周期请求汇总日志; 观测面提供同源指标出口、集群 Dashboard 与独立单 owner 平台 controller。
三个接入面:
- 注解:
#[grafana(max_concurrent = 50, timeout_ms = 800, tps = 1)](空参 = 只监控)。 - 显式:
Command::new/Command::monitor/Command::with_tps+run/run_fn。 - 配置驱动:yml 根
grafana.isolation+init_isolation+dispatch全局中间件。
受管 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、超时和双轨指标保护的命令(= 一个接口端点)。
- Fallback
Context - 交给业务全局降级处理器的稳定请求视图。
- Isolation
Rule - 一条隔离模式的参数;
#[derive(Deserialize)]让业务 yml 直接反序列化。 - Monitor
Conflict - 同 key 但参数不一致的注册冲突(
crate::Command::try_monitor的错误产物)。 - Prometheus
Metric Sample - 一个 nafana 指标 family 与 label 组合的结构化快照。
Enums§
- Fallback
Cause - 触发降级的运行时原因。
- Fallback
Decision - 业务全局降级处理器对当前事件的处理决定。
- Global
Fallback Install Error - 安装全局降级处理器时可能出现的唯一性错误。
- Prometheus
Metric Value - nafana registry 的 provider-neutral 当前值。
Traits§
- Global
Fallback Handler - 业务手动实现的进程级终态降级扩展点。
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
- 业务作用:
/metricshandler:业务把它挂到路由即可被 Prometheus 抓取。 是否鉴权由业务路由层自定(合同 安全边界);本组件不新增独立端口。 - metrics_
source - 业务作用:提供进程唯一的接口指标源,受管 Application 自动登记,独立宿主可显式登记。
- render_
metrics - 业务作用:渲染包含主请求、全局降级与事务权重事实的稳定 Prometheus 文本。
- structured_
metrics_ snapshot - 业务作用:直接从 nafana 全局 registry 读取与 Prometheus 出口同源的结构化当前值。
Type Aliases§
- Fallback
Fn - 降级 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 指标