EMQX 多租户按 Namespace 统计消息丢弃指标：`/api/v5/prometheus/namespaced_stats` 实战指南

EMQX 多租户按 Namespace 统计消息丢弃指标/api/v5/prometheus/namespaced_stats实战指南【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx导读在 EMQX 多租户multi-tenancyemqx_mt应用场景下不同租户共享同一个 broker而消息因无订阅者、投递队列满、消息过大等原因被丢弃是日常运维中最常见的异常信号之一。本指南介绍 EMQX 新增的按 namespace 统计的dropped messages丢弃消息与dropped deliveries丢弃投递计数器它们通过/api/v5/prometheus/namespaced_stats端点以 Prometheus 文本格式暴露并携带namespace标签。读完本文你将掌握如何通过 Prometheus 按租户定位丢弃率、理解计数器在源码中的触发链路与命名映射以及如何配置采集和告警。该功能对应的变更记录为 feat-17665.en.md归属于 EMQX 6.x 的多租户multi-tenancy能力。功能概览为多租户补齐每租户丢弃指标此前 EMQX 的emqx_messages_dropped、emqx_delivery_dropped等指标是全局统计的当多个租户共享一个 broker 时全局计数无法回答哪个租户丢得最多哪个租户的投递队列频繁打满这类问题运营者只能翻日志排查。本次新增的功能在emqx_mt多租户应用中为messages.dropped与delivery.dropped两类事件建立按 namespace 维度的计数器通过GET /api/v5/prometheus/namespaced_stats端点暴露输出为 Prometheus 文本格式每个指标家族都带有namespace标签并叠加node标签与已有的按 namespace 统计的指标家族如emqx_bytes_received、emqx_sessions_count等并列运营者可以直接从 Prometheus 按租户诊断丢弃率无需再依赖日志检索。从源码结构看这套能力由三部分协作完成emqx_mt应用中的 hook 回调负责记账emqx_mt_hookcb.erlemqx_prometheus应用负责聚合与渲染emqx_prometheus.erlemqx_prometheus_api.erl负责对外暴露emqx_prometheus_api.erl。一、端点与请求参数端点在emqx_prometheus_api模块中注册见 emqx_prometheus_api.erl 的paths/0GET /api/v5/prometheus/namespaced_stats它对应的 OpenAPI schema 定义了如下查询参数见schema(/prometheus/namespaced_stats)与fields/1参数类型必填默认值说明modeenum否node数据采集模式可选node、all_nodes_aggregated、all_nodes_unaggregated定义见 emqx_prometheus.hrlnsstring否当前请求者的 namespace指定要查询的租户 namespace不传时返回全部 namespace或当前登录者可见的 namespace请求示例# 查询单个 namespace 的指标node 模式 curl -u admin:public \ http://127.0.0.1:18083/api/v5/prometheus/namespaced_stats?modenodenstenant_a # 查询集群所有 namespace 的指标聚合模式 curl -u admin:public \ http://127.0.0.1:18083/api/v5/prometheus/namespaced_stats?modeall_nodes_aggregated几点行为说明响应格式端点只返回 Prometheus 文本格式text/plain。若请求头声明Accept: application/json会被validate_not_json/2过滤器以400 only prometheus format is supported拒绝——JSON 指标格式已不再支持emqx_prometheus_api.erl。认证该端点属于监控MONITORING权限域schema 的security()会根据配置项prometheus.enable_basic_auth决定是否要求 basic auth / bearer auth。权限隔离namespaced 管理员 / API Key 只能查询自己所在 namespace的数据全局管理员可以查看全部 namespace详见后文权限与边界。限流当查询范围为全部 namespaceall时会经由emqx_prometheus_limiter做消费限流超限返回429 Too many requests见rate_limit_all_ns_stats/2。二、新增的指标家族与命名映射按 namespace 统计的丢弃指标在 Prometheus 文本输出中以namespace标签区分租户。下面列出本次新增涉及的两类指标家族及其与内部计数器名的对应关系定义见 emqx_prometheus.erl 的message_metric_meta/0与delivery_metric_meta/0该两份元数据同时被 per-namespace 采集复用丢弃消息messages.droppedPrometheus 指标名内部计数器说明emqx_messages_droppedmessages.dropped丢弃消息总数伞形计数器emqx_messages_dropped_no_subscribersmessages.dropped.no_subscribers因无订阅者而丢弃全局维度下另有messages.dropped.await_pubrel_timeout、messages.dropped.quota_exceeded、messages.dropped.receive_maximum等细粒度计数器但它们不参与 per-namespace 计数原因见下文实现原理。丢弃投递delivery.droppedPrometheus 指标名内部计数器说明emqx_delivery_droppeddelivery.dropped丢弃投递总数伞形计数器emqx_delivery_dropped_no_localdelivery.dropped.no_local因no_local订阅选项丢弃emqx_delivery_dropped_too_largedelivery.dropped.too_large因消息过大丢弃emqx_delivery_dropped_qos0_msgdelivery.dropped.qos0_msg因 QoS 0 消息丢弃emqx_delivery_dropped_queue_fulldelivery.dropped.queue_full因接收方队列满丢弃emqx_delivery_dropped_expireddelivery.dropped.expired因消息过期丢弃在emqx_prometheus的collect_mf(?PROMETHEUS_NS_STATS_REGISTRY, Callback)分支中message_metric_ns_meta()与delivery_metric_ns_meta()被显式挂载到 per-namespace registryemqx_prometheus.erl因此渲染出的文本形如# HELP emqx_messages_dropped # TYPE emqx_messages_dropped counter emqx_messages_dropped{nodeemqx127.0.0.1,namespacetenant_a} 12 emqx_messages_dropped_no_subscribers{nodeemqx127.0.0.1,namespacetenant_a} 7 emqx_delivery_dropped_queue_full{nodeemqx127.0.0.1,namespacetenant_a} 3emqx_mt_SUITE中的测试t_namespaced_metrics_prometheus_delivery_dropped明确断言渲染文本必须包含带 namespace 标签且值非零的emqx_delivery_dropped家族emqx_mt_SUITE.erl可作为预期输出的权威参考。三、实现原理drop 事件如何变成 per-namespace 计数1. 挂载 hook在最低优先级记账emqx_mt_hookcb:register_hooks/0将多租户的丢弃事件回调注册到全局 hook 上emqx_mt_hookcb.erlok emqx_hooks:add(message.dropped, ?MSG_DROPPED_HOOK, ?HP_LOWEST), ok emqx_hooks:add(delivery.dropped, ?DELIVERY_DROPPED_HOOK, ?HP_LOWEST),注释明确说明drop 事件 hook 以最低优先级?HP_LOWEST注册确保过滤器、规则引擎等更高优先级的处理器已先执行完多租户记账不会干扰正常业务处理。2. 从消息 / 客户端信息中解析 namespacenamespace 的判定依据是客户端属性中的租户标识?CLIENT_ATTR_NAME_TNS对message.dropped从#message.headers.client_attrs中取tnsns_from_msg/1对delivery.dropped优先取目标客户端ClientInfo.client_attrs.tns缺失时回退到消息头ns_from_clientinfo/2。若取不到 namespace非多租户客户端则跳过计数inc_ns(undefined, _Names) - ok保证全局流量不受影响emqx_mt_hookcb.erl。3. drop 原因到计数器名的映射drop_metric_names/2将丢原因映射为伞形计数器 原因细粒度计数器的列表每次事件对列表逐项自增drop_metric_names(messages.dropped, no_subscribers) - [messages.dropped, messages.dropped.no_subscribers]; drop_metric_names(delivery.dropped, expired) - [delivery.dropped, delivery.dropped.expired]; drop_metric_names(delivery.dropped, no_local) - [delivery.dropped, delivery.dropped.no_local]; drop_metric_names(delivery.dropped, qos0_msg) - [delivery.dropped, delivery.dropped.qos0_msg]; drop_metric_names(delivery.dropped, queue_full) - [delivery.dropped, delivery.dropped.queue_full]; drop_metric_names(delivery.dropped, too_large) - [delivery.dropped, delivery.dropped.too_large]; %% 其余原因只累加伞形计数器最终通过emqx_metrics:inc_safe(Ns, Name)落账。值得注意的边界QoS2 的 PUBREL 等待超时await_pubrel_timeout不属于消息丢弃——EMQX 在 PUBLISH 到达时就已经把 QoS2 消息发布给订阅者之后过期的只是报文 ID 去重状态因此该原因不产生 per-namespace 计数器见 emqx_mt_hookcb.erl 的注释说明。四、数据采集链路从端点请求到 Prometheus 文本一次namespaced_stats请求的处理链路如下emqx_prometheus_api.erlns_stats/2 └─ collect_ns_stats(#{mode, namespace}) └─ emqx_prometheus:collect_ns(Namespace, Mode) ├─ 设置 process dictionary 中的 mode 与 namespace └─ prometheus_text_format:format(?PROMETHEUS_NS_STATS_REGISTRY)其中?PROMETHEUS_NS_STATS_REGISTRY即emqx_prometheus_ns_stats注册表emqx_prometheus.hrl。集群聚合逻辑在 emqx_prometheus_cluster.erl 的raw_data_ns/3中node 模式只取本地节点的fetch_namespaced_metrics_v1(Namespace, Mode)再合并集群一致数据all_nodes_aggregated / all_nodes_unaggregated 模式通过emqx_prometheus_proto_v3:raw_prom_data/5对支持该 BPAPI 版本的节点发起 RPC分别做求和聚合或逐节点并列。请求时若不指定ns在collect_opts_ns_or_all/1中会被归一为all全量 namespace并走限流保护。五、权限与边界行为两个后续修复与本次功能同属该指标体系值得了解namespaced 数据隔离namespaced 管理员 / API Key 只能看到自己 namespace 的数据。parse_namespace/1会比对查询参数ns与请求者身份 namespace当非全局用户在ns中指定了别人的 namespace 时返回403 User not authorized to operate on requested namespaceemqx_prometheus_api.erl。对应变更记录fix-17757.en.md。未知 namespace 不输出零值指标当请求的 namespace 不存在时其指标会整体从输出中省略而不是输出全零序列与采集全部 namespace时的行为保持一致。对应变更记录fix-18292.en.md相关修复记录见 6.2.3.en.md。emqx_prometheus_api_2_SUITE的t_namespaced_stats用大量断言覆盖了这些行为无认证时 401、全局管理员可见全部 namespace 且可单点过滤、namespaced 管理员只能看到自己的 namespaceemqx_prometheus_api_2_SUITE.erl。六、测试验证计数器与渲染的正确性仓库在apps/emqx_mt/test/emqx_mt_SUITE.erl中为本次功能提供了系统化测试第 2140 行起注释明确标注 Per-namespace counters for dropped messages and dropped deliveries测试用例验证点t_namespaced_metrics_dropped_no_subscribers带显式 namespace 的客户端发布到无订阅者主题时messages.dropped与messages.dropped.no_subscribers的全局计数保持 0而该 namespace 的计数为 1t_namespaced_metrics_dropped_no_subscribers_implicit不带租户 namespace 的客户端global 上下文触发丢弃时只累加全局计数不污染任何 namespace 计数t_namespaced_metrics_delivery_dropped_no_localno_local订阅选项导致投递被丢弃时delivery.dropped与delivery.dropped.no_local按 namespace 自增t_namespaced_metrics_prometheus_delivery_dropped通过emqx_prometheus:fetch_namespaced_metrics_v1/2拉取的数据必须包含delivery_data_ns且渲染的 Prometheus 文本中emqx_delivery_dropped家族带namespace标签且值非零这些测试同时印证了显式 namespace 才记账global 流量不污染租户统计原因细粒度计数器存在且正确映射三个关键语义。七、在 Prometheus 中落地采集配置与告警示例配置 scrape让 Prometheus 定时抓取该端点即可获得每租户的丢弃曲线以下为通用 Prometheusscrape_configs写法按你的实际监控架构调整scrape_configs: - job_name: emqx_namespaced_stats metrics_path: /api/v5/prometheus/namespaced_stats scheme: http basic_auth: username: admin password: your-password static_configs: - targets: [127.0.0.1:18083] params: mode: [all_nodes_aggregated]按租户诊断丢弃率基于namespace标签即可做按租户分析标准 PromQL# 各租户丢弃消息速率 sum by (namespace) (rate(emqx_messages_dropped[5m])) # 某租户的投递队列打满速率 rate(emqx_delivery_dropped_queue_full{namespacetenant_a}[5m]) # 丢弃占发布的比例近似丢弃率按租户 sum by (namespace) (rate(emqx_messages_dropped[5m])) / on (namespace) sum by (namespace) (rate(emqx_messages_publish[5m]))配合告警规则例如任一租户 5 分钟内delivery.dropped_queue_full持续上升即可在租户感知tenant-aware的粒度上主动发现配额不足、订阅配置异常或连接质量问题这正是本次功能免日志排障的设计目标。总结本次变更PR #17665见 feat-17665.en.md为 EMQX 多租户应用补齐了按 namespace 的丢弃消息与丢弃投递计数器经由/api/v5/prometheus/namespaced_stats以携带namespace标签的 Prometheus 文本格式输出。其实现分三层emqx_mt_hookcb在最低优先级挂载 drop 事件 hook 并按租户记账、emqx_prometheus通过独立的emqx_prometheus_ns_stats注册表聚合渲染、emqx_prometheus_api负责对外暴露与权限隔离。结合配套测试与后续修复这套指标从记账、聚合到渲染、鉴权均已形成闭环为多租户运营提供了从 Prometheus 直接按租户诊断丢弃率的可靠途径。【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考