fhEVM Listener Grafana 监控大盘实战双仪表盘架构、指标边界与告警规则全解【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本篇指南聚焦 fhEVM 仓库中listener组件自带的 Grafana 观测体系它如何通过Per-Chain单链深潜与Fleet集群与基础设施两张仪表盘沿真实数据边界拆分链内建指标、RPC 提供方指标与 Broker 指标并配套开箱即用的 Prometheus 告警规则与多链采集方案。读完本文你将掌握两张仪表盘的面板结构、模板变量、健康/劣化判读标准能独立完成导入部署、多链接入与告警规则裁剪并理解其背后的指标标签设计原理对应文档dashboard.md、metrics.md。为什么需要两张仪表盘Listener 对外暴露的 Prometheus 指标默认:9090的/metrics端点由配置中telemetry.enabled: true开启天然分为三个类别每一类携带的标签完全不同指标类别示例指标固有标签链内建Chain-intrinsiclistener_cursor_iterations_total、listener_reorgs_total、listener_*_block_number、listener_*_fetch_duration_seconds、listener_transient/permanent/publish_errors_totalchain_idRPC 提供方RPC providerlistener_rpc_*method、endpoint无chain_idBrokerbroker_*topic、backend、outcome等无chain_id如果把三个类别强行塞进同一张以$chain_id过滤的仪表盘RPC 与 Broker 面板就会显示No data——因为这些指标根本不携带chain_id。Broker 是共享的 Redis/RabbitMQ 实例RPC 指标则跨所有 listener 实例聚合它们本来就属于基础设施而非某一条链。因此仓库的解决方案是沿真实数据边界拆分listener.jsonuidlistener-per-chain 只放链内建指标统一以$chain_id过滤任何面板都有数据listener-fleet.jsonuidlistener-fleet 跨链汇总按chain_id分组 共享 RPC 共享 BrokerRPC/Broker 面板不做链过滤。两张仪表盘均为Grafana 12.x 有效导出JSON 的__requires中声明了 Grafana 12.0.0 与 Prometheus datasource 依赖消费的指标全部定义在 metrics.md 中。只有chain_id没有network标签chain_id是 EIP-155 网络标识符唯一对应一条 EVM 网络1 Ethereum 主网、11155111 Sepolia 等。按chain_id排序与分组已经足够两张仪表盘刻意不依赖独立的network标签因此无需任何特殊的 Prometheus scrape 配置即可工作。从源码看endpoint标签是配置中rpc_url的host 部分在 sem_evm_rpc_provider.rs 中通过Url::host_str()提取解析失败时回退为unknown。URL 路径或查询串中内嵌的 API Key故意不对外暴露只输出 host保证 Prometheus 抓取不含密钥配置的rpc_url输出的endpoint标签https://ethereum-rpc.publicnode.comethereum-rpc.publicnode.comhttps://eth-mainnet.g.alchemy.com/v2/MY_SECRET_KEYeth-mainnet.g.alchemy.comhttps://mainnet.infura.io/v3/MY_PROJECT_IDmainnet.infura.io导入方式方式 A自动配置推荐Grafana 的 provisioning 配置 default.yml 监听/etc/grafana/dashboards目录并自动导入其中的所有 JSON 文件。两张仪表盘已通过 docker-compose.yamlgrafana服务profiles: [monitoring]挂载进 Grafana 容器docker compose --profile monitoring up # Grafana → http://localhost:3000 (admin/admin)从 docker-compose.yaml 可以看到grafana 服务将listener.json、listener-fleet.json、erpc.json三个文件全部挂载进容器同时挂载 datasource 自动配置与default.ymlprovisioning 配置Prometheus 与 Grafana 使用同一个monitoringprofile 一并启动。方式 B手动上传Grafana UI →Dashboards→New→Import→ 上传 JSON 文件 → 选择 Prometheus datasource。仪表盘 1Evm Listener - Per Chain单链深潜listener.jsonuidlistener-per-chain。面向值班工程师on-call对单条链做深度排查。模板变量变量类型用途datasourcedatasourcePrometheus 数据源chain_idquery单选选择要查看的链取值来源label_values(listener_cursor_iterations_total, chain_id)面板行RowsOverview概览5 个 stat常驻展开Chain Height、DB Tip、Sync Lag、Cursor Rate每分钟迭代数、Reorgs 24h——全部以$chain_id过滤。Cursor Sync游标与同步区块高度链侧 vs 数据库、同步滞后时序、游标迭代速率、重组柱状图。Block Fetch Performance区块抓取性能单区块抓取热力图 p50/p95/p99区间抓取热力图 p50/p95/p99。Listener Errors监听错误按类别统计的瞬时错误、按类别统计的永久错误、发布错误速率。Block Compute Verification区块计算校验按失败类型分为两个子区交易根、回执根、区块哈希24h 计数器顶部 stat 面板最近 24 小时计算失败总数——快速回答今天出过问题吗速率时序底部按stalling标签拆分的失败速率。stallingfalse属于宽松跳过数据质量问题stallingtrue属于硬停机不变量问题。Catchup追赶实时流水线编排器速率、跳过当前链头计数与扇出子区间 24h 计数、子区间耗时 p95 分位数、计数速率时序——实时追赶流水线全貌。Finality终局性迭代速率停滞检测、终局滞后区块数final height − final tip、终局激活 on/off stat、区间耗时 p95、final tip 与 final height 时序、区间耗时分位数。Final Catchup终局追赶与 Catchup 行相同的面板组但基于listener_final_catchup_*指标钳制在 final height 而非链头。健康 vs 劣化判读面板健康劣化处置动作Chain Height单调递增走平去 fleet 仪表盘查 RPC 面板DB Tip单调递增走平且远低于链高检查抓取性能行Sync Lag 5区块绿≥ 20红检查单块/区间抓取耗时Cursor Rate 0次/分钟0红游标停滞——查错误行 fleet RPC 面板Reorgs 24h依链而定异常突增与上游链事件交叉核对Transient errors低且呈突发状持续速率通常是 RPC 或 Broker 基础设施问题——跳到 fleet 仪表盘Permanent errors始终为零出现任何非零不变量被破坏 逻辑缺陷立即排查Publish errors零持续 0Broker 宕机或消费者队列缺失——跳 fleet Broker 行Compute failures 24h计数器严格链上为 0带跳过的 L2 上较小且依链而定持续增长与速率面板交叉核对是突发还是趋势Compute failures ratestallingfalse低依链而定持续速率排查 RPC 数据质量多为不支持的 L2 交易类型Compute failures ratestallingtrue始终为零出现任何非零区块校验硬失败——检查 RPC 节点或区块计算机编码Finality Active启用终局时1配置已启用却是0配置/部署不匹配——检查finality_activeFinality Iterations Rate激活时 0激活却为0红终局循环停滞——查错误行缺 final 事件消费者队列见 error_flows.mdFinality Lag接近该链的终局窗口稳定无界增长终局流水线跟不上——查区间耗时 fleet RPC 面板仪表盘 2Evm Listener - Fleet and Infrastructure集群与基础设施listener-fleet.jsonuidlistener-fleet。面向SRE 负责人跨链健康 共享 RPC/Broker 概览。模板变量变量类型适用面datasourcedatasource所有面板endpointquery多选默认 all仅 RPC 行——按 RPC 提供方 host 过滤topicquery多选默认 allBroker 行——按路由键过滤backendquery多选默认 allBroker 行——redis/amqp刻意不设chain_id变量——这张仪表盘本质就是跨链的。面板行Fleet Overview集群概览Fleet Health表格每个chain_id一行列为chain height、db tip、sync lag、cursor/min、reorgs 24h、transient 1h、permanent 1h按 sync lag 降序排序条件着色标记劣化链。这是回答整个集群现在怎么样的首选视图。从 listener-fleet.json 可见其查询为sum by (chain_id) (...)的实例查询组合sync lag与permanent 1h列带阈值着色覆盖。Sync Lag per Chain时序每条链一个序列表达式为listener_chain_height_block_number - listener_db_tip_block_number。Cursor Iteration Rate per Chain跨集群检测停滞。Reorgs per Chain1h 桶突增检测器。Listener Errors per Chaintransient / permanent / publish 堆叠每个(chain_id, kind)一个序列。点击右上角Per-chain deep dive链接即可跳转到listener.json深挖单条链两个 JSON 中通过 dashboard 级links互链分别指向/d/listener-fleet与/d/listener-per-chain。RPC Provider跨链共享RPC Request Rate按(method, endpoint)流量画像。RPC Success Ratio by endpointsuccess / (successerror)按提供方对比一眼比较 Alchemy vs Infura vs 自建节点。RPC p95 Latency按(method, endpoint)逐提供方慢查询定位。RPC Errors按(endpoint, error_kind)错误分类。RPC Semaphore Available by endpoint饱和度指示0 饱和。Top Failing (method, endpoint, error_kind) — 24h即时诊断表。RPC 指标的method标签取值包括eth_blockNumber、eth_chainId、eth_getBlockByNumber、eth_getBlockByHash、eth_getTransactionReceipt、eth_getBlockReceipts、eth_getTransactionReceipt_batcherror_kind标签取值包括deserialization、unsupported_method、rate_limited、transport、not_found、batch_error、batch_unsupported详见 metrics.md。Broker — Publishing折叠按 topic 的发布速率、按类别错误、耗时热力图、按 topic 的 p95。Broker — Consuming折叠按outcomeack/nack/dead/delay/transient/permanent的消费速率、handler 耗时热力图 p95、按原因的死信、投递次数分布。Broker — Queue Depth折叠Principal / retry / dead-letter / pending / lag每个 topic 一个序列。DLQ 深度持续爬升 消息系统性失败。Broker — Circuit Breaker Connection折叠熔断器状态0closed1open2half-open、跳闸次数、连续失败数、消费者连接 stat、重连速率、claim sweeper 统计。Finality — Fleet折叠Finality Active by Chainlistener_finality_active每条链一个 0/1 序列——一眼找出终局流程未开启的链。Finality Lag by Chainlistener_final_height_block_number - listener_final_tip_block_number逐链。Finality Iteration Rate by Chain跨集群检测终局停滞。Final Catchup Sub-ranges Rate by Chain逐链回放活跃度。终局相关队列fetch-final-block、clean-final-blocks、final-catchup、range-final-catchup会通过topic变量自动出现在Broker — Queue Depth行中。从 metrics.md 的说明可知终局流程同样会喂入共享指标区块抓取计入listener_block_fetch_duration_secondsget_final_block_number调用出现在 RPC 指标里错误进入分类计数器终局队列注册进 Broker 队列深度轮询器。多链部署每个链一个实例一个 scrape job每个链部署一个 listener 实例各自配置指向自己的 RPC 提供方参见 listener-1.yaml 中的chain_id: 1、rpc_url与network: ethereum-mainnet。每个实例发出的指标自带各自chain_id标签Prometheus 自动聚合两张仪表盘随之自动填充listener.json→chain_id下拉框从label_values(listener_cursor_iterations_total, chain_id)自动填充listener-fleet.json→ fleet 表格每链自动增长一行RPC/Broker 行跨所有实例聚合。无需任何 scrape 配置体操只需在 prometheus.yml 中每链加一个抓取任务scrape_configs: - job_name: listener-ethereum static_configs: - targets: [listener-eth:9090] - job_name: listener-sepolia static_configs: - targets: [listener-sep:9090]仪表盘不需要任何外部注入的chain_id标签——它们直接读取 listener 自身发出的固有chain_id标签。可选如果希望在chain_id旁展示人类可读的网络名可在 scrape job 上加一个network: ethereum-mainnet标签。当前没有任何仪表盘使用它但它是一个无害的自由文本注解可在告警或自定义面板中引用。仓库自带的 prometheus.yml 正是这样做的——它在labels:块里同时附加chain_id与network到该目标抓取的所有指标上。关于抓取频率的一个底层细节指标文档中特别强调所有 gauge 在启动时初始化为0让 Grafana 在第一次抓取时就能发现时序甚至在首次游标迭代完成之前listener_compute_{block,transaction,receipt}_failure_total三个计数器还会针对每个{chain_id, stalling}组合true/false预置 0。原因在于 Prometheus 的increase()/rate()至少需要回看窗口内的两个采样点才能算出增量——若计数器从缺失直接跳到124h 的increase()会报告0。预置 0 让首次真实失败立刻以1呈现在 stat 面板与告警中。推荐的 Prometheus 告警规则将以下规则加入 alert.rules该文件已由 prometheus.yml 的rule_files引用并在 docker-compose.yaml 中挂载进 Prometheus 容器groups: - name: listener rules: - alert: ListenerCursorStall expr: rate(listener_cursor_iterations_total[5m]) 0 for: 5m labels: { severity: critical } annotations: summary: Listener cursor stalled on chain {{ $labels.chain_id }} - alert: ListenerSyncLagHigh expr: (listener_chain_height_block_number - listener_db_tip_block_number) 50 for: 10m labels: { severity: warning } annotations: summary: Sync lag 50 blocks on chain {{ $labels.chain_id }} - alert: ListenerReorgStorm expr: increase(listener_reorgs_total[1h]) 10 labels: { severity: warning } annotations: summary: More than 10 reorgs in the last hour on chain {{ $labels.chain_id }} - alert: ListenerPermanentError expr: increase(listener_permanent_errors_total[5m]) 0 labels: { severity: critical } annotations: summary: Permanent (invariant) error on chain {{ $labels.chain_id }}: {{ $labels.error_kind }} - alert: ListenerRpcErrorRateHigh expr: | sum by (endpoint) (rate(listener_rpc_errors_total[5m])) / sum by (endpoint) (rate(listener_rpc_requests_total[5m])) 0.05 for: 5m labels: { severity: warning } annotations: summary: RPC error rate 5% on {{ $labels.endpoint }} - alert: ListenerRpcSemaphoreExhausted expr: listener_rpc_semaphore_available 0 for: 2m labels: { severity: warning } annotations: summary: RPC semaphore saturated on {{ $labels.endpoint }} - alert: BrokerCircuitBreakerOpen expr: broker_circuit_breaker_state 1 for: 2m labels: { severity: critical } annotations: summary: Broker circuit breaker OPEN on {{ $labels.topic }} - alert: BrokerDlqGrowing expr: deriv(broker_queue_depth_dead_letter[15m]) 0 for: 15m labels: { severity: warning } annotations: summary: Dead-letter queue growing on {{ $labels.topic }}规则设计要点游标停滞critical对应 metrics.md 中的停滞判定rate(...[5m]) 0意味着游标卡住永久错误critical是最重要的规则——listener_permanent_errors_total的error_kind取值为invariant_violation来自InvariantViolation错误时属于逻辑缺陷其余 8 个error_kindblock_fetch、block_compute、database、chain_height、slot_buffer、broker_publish、payload_build、message_processing均为瞬时错误走熔断与 Broker 重试RPC 错误率、信号量饱和与 Broker 熔断规则针对的是共享基础设施天然无chain_id适合在 fleet 层面告警。若需要针对区块计算校验失败追加告警可参照 metrics.md 提供的候选表达式按stallingtrue聚合三类校验失败计数并分组告警。自定义与扩展按环境改名修改每个 JSON 底部的title和uid字段例如Evm Listener [staging] - Per Chain。新增链无需改动仪表盘——listener.json的chain_id变量自动填充fleet 表格自动增长一行仅需按上文在多链部署一节追加 scrape job。修改刷新频率与默认时间范围编辑每个 JSON 底部的refresh与time字段。新增面板在 Grafana UI 中打开仪表盘 → 编辑 → 保存 → 导出 JSON → 替换仓库文件。面板id在仪表盘内必须唯一。关联文档listener/docs/metrics.md — 原始指标定义、标签、Grafana 查询示例listener/monitoring/prometheus/prometheus.yml — 带注释的多链 scrape 配置listener/monitoring/grafana/dashboards/default.yml — Grafana provisioning 配置listener/docs/error_flows.md — 错误流与终局消费者队列缺失等故障排查listener/docker-compose.yaml —monitoringprofile 下 Prometheus Grafana 的一键编排。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考