fhEVM Listener Prometheus Metrics 全量指标目录：从采集配置到告警实战

fhEVM Listener Prometheus Metrics 全量指标目录从采集配置到告警实战【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本文是 fhEVM 开源仓库中 Listener 指标目录 的深度展开。Listener 是 fhEVM 架构中负责订阅链上区块事件、校验后经 Broker 发布给下游Coprocessor、KMS Connector、Relayer的核心组件其可观测性直接决定生产环境的排障效率。读完本文你将掌握 Listener 通过telemetry配置暴露 Prometheus 指标的具体方法、Listener Core / RPC Provider 全量指标语义与标签设计、基于这些指标编写 Grafana 面板和告警规则含游标停滞、同步滞后、RPC 供应商对比、计算校验失败等场景的完整 PromQL 方案以及这些指标在源码中的注册、初始化和分类实现。一、指标暴露入口与启用方式Listener 的 Prometheus 指标由二进制内置的 HTTP 服务在/metrics端点暴露默认监听:9090。其开关与端口由telemetry配置段控制定义在 config.rs 的TelemetrySettings结构体中/// Telemetry / metrics configuration. /// /// When enabled is true (default), the binary starts a Prometheus HTTP /// server on metrics_port that serves /metrics. pub struct TelemetrySettings { /// Enable the Prometheus metrics endpoint. Default: true. #[serde(default default_telemetry_enabled)] pub enabled: bool, /// Port for the Prometheus /metrics endpoint. Default: 9090. #[serde(default default_metrics_port)] pub metrics_port: u16, }对应的实际配置文件如 config.yaml写法为telemetry: enabled: true metrics_port: 9091要点说明enabled默认值为true即不写该配置项时指标端点也会开启显式设为false可关闭。metrics_port默认值为9090。仓库内多个示例配置使用了不同端口以避免多实例冲突默认 config.yaml 用9091config-minimal.yaml 与 config-polygon-compute.yaml 用9092config-avalanche.yaml 用9093。多链/多实例部署时建议为每个实例分配独立端口再由 Prometheus 的targets分组采集。指标注册入口在 metrics.rs 的describe_metrics()它在应用启动、安装 metrics exporter 之后调用一次幂等可重复调用。所有指标统一以listener_前缀命名与 Broker 自身的broker_*指标相互独立。二、Listener Core 指标游标、同步、重组织与发布Listener Core 是执行区块抓取、校验、入库和发布的主循环其指标按功能域划分如下。2.1 游标活跃度Cursor LivenessMetricTypeLabelsDescriptionlistener_cursor_iterations_totalCounterchain_id主游标循环累计迭代次数。停滞检测rate(...[5m]) 0说明游标卡住。该计数器在主循环入口 evm_listener.rs 的fetch_blocks_and_run_cursor()中每次迭代increment(1)。它是整个 Listener 健康度的心跳优先监控项任何时刻该指标 5 分钟速率为 0 都意味着游标不再前进应触发告警。2.2 链同步Chain SyncMetricTypeLabelsDescriptionlistener_db_tip_block_numberGaugechain_id数据库已持久化的最新规范canonical区块号。listener_chain_height_block_numberGaugechain_idRPC 节点报告的最新区块号。同步滞后Sync lag定义为两者差值sync_lag listener_chain_height_block_number - listener_db_tip_block_numberdb_tip代表 Listener 自身的处理进度chain_height代表链的真实高度。两者之差即落后链头多少区块是衡量追赶能力特别是重启或回补后的核心指标。值得注意这两个 Gauge 在 init_gauges() 中于启动时被显式置0保证 Grafana 在第一次抓取时即可发现时间序列。2.3 重组织ReorgsMetricTypeLabelsDescriptionlistener_reorgs_totalCounterchain_id游标检测到的链重组累计次数。游标在检测到ReorgDetected时递增该计数器见 evm_listener.rs 附近逻辑。重组织频率反映所订阅链的最终性质量波动剧烈时需关注节点同步状态或考虑启用最终性流程。2.4 抓取耗时Fetch TimingMetricTypeLabelsDescriptionlistener_block_fetch_duration_secondsHistogramchain_id抓取单个区块RPC 调用 收据的墙钟耗时。listener_range_fetch_duration_secondsHistogramchain_id抓取并处理一整段区块范围生产者 消费者的墙钟耗时。两者均为 Histogram适合用histogram_quantile计算 P99/P95 延迟。range_fetch是批量处理的端到端耗时最能反映吞吐瓶颈——若区块级延迟正常而范围级延迟升高问题可能出在消费者/入库环节。2.5 发布PublishingMetricTypeLabelsDescriptionlistener_publish_errors_totalCounterchain_id向 Broker 发布区块事件失败次数。每次失败发布尝试递增一次在 Broker 级重试耗尽之后。该指标与 Broker 的broker_publish_errors_total含义互补前者是 Listener 侧的最终失败次数后者是 Broker 通道内部的错误。两者同时观测可以区分消息根本没发出去与发送过程中出错后由重试消化两种场景。2.6 追赶流程Catchup实时流当 Listener 落后于链头时由 orchestrator 驱动的 catchup 流程负责快速补齐MetricTypeLabelsDescriptionlistener_catchup_iterations_totalCounterchain_id在 principalcatchup队列上收到的 CatchupPayload 数量orchestrator 调用。listener_catchup_skipped_above_head_totalCounterchain_idorchestrator 跳过次数block_start高于当前链头。listener_catchup_subranges_totalCounterchain_idorchestrator 扇出到range-catchup的子范围数量。listener_catchup_range_duration_secondsHistogramchain_id抓取并发布单个 catchup 子范围的墙钟耗时。从源码实现看catchup 采用主队列接收任务、按子范围扇出到range-catchup队列并行处理的两级结构因此subranges_total反映扇出规模range_duration_seconds反映每个并行子任务的耗时。若skipped_above_head_total持续增长说明 orchestrator 收到大量已过期的追赶请求可能是调度配置不当。2.7 最终性流程Finality针对需要等待最终确认finalized的链Listener 提供独立的最终性处理链路MetricTypeLabelsDescriptionlistener_finality_iterations_totalCounterchain_id最终性循环迭代次数。停滞检测流程活跃时速率应大于 0。listener_final_tip_block_numberGaugechain_id数据库中最新最终区块号final_blockstip。listener_final_height_block_numberGaugechain_idRPC 节点报告的最新最终区块号finalized标签或head - finality_depth。与 tip 的差值即最终性滞后区块数。listener_finality_range_fetch_duration_secondsHistogramchain_id抓取、发布并插入一整段最终区块范围的墙钟耗时。listener_finality_activeGaugechain_id该链是否启用最终性流程1 启用0 未启用。用于区分未启用与已停滞。listener_finality_active是一个非常有用的状态标识Gauge仅凭finality_iterations_total的速率无法判断流程关闭还是流程卡死而该 Gauge 让你在编写告警时把两种情形区分开——例如finality_iterations速率低但finality_active 1才真正告警。2.8 最终性追赶Final CatchupMetricTypeLabelsDescriptionlistener_final_catchup_iterations_totalCounterchain_id在 principalfinal-catchup队列上收到的 CatchupPayload 数量orchestrator 调用。listener_final_catchup_skipped_above_head_totalCounterchain_idorchestrator 跳过次数block_start高于当前最终高度。listener_final_catchup_subranges_totalCounterchain_idorchestrator 扇出到range-final-catchup的子范围数量。listener_final_catchup_range_duration_secondsHistogramchain_id抓取并发布单个最终性追赶子范围的墙钟耗时。最终性流程与共享指标的关系见原文档说明结合源码可印证区块抓取计入listener_block_fetch_duration_secondsget_final_block_number调用出现在 RPC 指标中对应eth_getBlockByNumber(finalized)或eth_blockNumber错误通过分类计数器transient/permanent流动最终性队列fetch-final-block、clean-final-blocks、final-catchup、range-final-catchup注册在 Broker 的队列深度轮询器上即broker_queue_depth_*系列。最终性策略的底层实现在 sem_evm_rpc_provider.rsget_final_block_number()根据finality_tag选择eth_getBlockByNumber(finalized)策略 A或head - finality_depth策略 B后者对链龄小于深度的新链会saturating_sub到 0。2.9 错误分类Error ClassificationMetricTypeLabelsDescriptionlistener_transient_errors_totalCounterchain_id,error_kind处理器错误分类器判定为瞬时基础设施类错误。触发熔断器和 Broker 重试。listener_permanent_errors_totalCounterchain_id,error_kind判定为永久逻辑类错误。直接进入死信队列dead-letter不重试。error_kind标签取值与EvmListenerError变体的映射定义在 error_kind_label()ValueSource ErrorTransient/Permanentblock_fetchCouldNotFetchBlockTransientblock_computeCouldNotComputeBlockTransientdatabaseDatabaseErrorTransientchain_heightChainHeightErrorTransientslot_bufferSlotBufferErrorTransientbroker_publishBrokerPublishErrorTransientpayload_buildPayloadBuildErrorTransientmessage_processingMessageProcessingErrorTransientinvariant_violationInvariantViolationPermanent设计意图非常清晰瞬时错误代表基础设施抖动可以通过重试消化对应熔断器与 Broker 重试机制永久错误代表逻辑不可能发生重试无意义必须死信化并人工介入。监控时重点盯permanent_errors_total——它通常意味着代码 bug 或数据异常应触发即时告警。2.10 区块计算校验Block Compute VerificationListener 在计算区块时会校验区块哈希、交易根、收据根防止静默的数据损坏MetricTypeLabelsDescriptionlistener_compute_block_failure_totalCounterchain_id,stalling区块哈希校验失败次数。stallingtrue表示 Listener 因此错误而停摆stallingfalse表示跳过allow_skipping模式。listener_compute_transaction_failure_totalCounterchain_id,stalling交易根校验失败次数。stalling语义同上。listener_compute_receipt_failure_totalCounterchain_id,stalling收据根校验失败次数。stalling语义同上。stalling标签取值ValueMeaningtruecompute_block_allow_skipping: false—— 校验失败使 Listener 停摆错误向上传播falsecompute_block_allow_skipping: true—— 校验失败仅记录日志并跳过宽松模式stallingtrue的任一失败指标出现即代表数据完整性受损是最高优先级的告警候选PromQL 见下文告警候选一节。三、RPC Provider 指标SemEvmRpcProviderListener 对 RPC 节点的每次 JSON-RPC 调用都通过SemEvmRpcProvider封装使用信号量Semaphore限制并发并系统化记录耗时与错误MetricTypeLabelsDescriptionlistener_rpc_request_duration_secondsHistogrammethod,endpoint每次 JSON-RPC 调用的墙钟耗时含信号量等待时间。listener_rpc_requests_totalCountermethod,endpoint,statusRPC 请求总数。status取值为success或error。listener_rpc_errors_totalCountermethod,endpoint,error_kind按失败类型细分的 RPC 错误数。listener_rpc_semaphore_availableGaugeendpointRPC 并发信号量中剩余可用许可数。低值表示 RPC 趋于饱和。从实现看信号量在 SemEvmRpcProvider::new() 中以max_concurrent_requests初始化并在每次请求获取许可后立即上报listener_rpc_semaphore_available见raw_request中的gauge!.set(...)。同时 HTTP 客户端被调优为 25 秒请求超时、3 秒连接超时、10 秒空闲连接回收、TCP keepalive 15 秒以适配慢速供应商与 Kubernetes 网络环境。3.1endpoint标签只暴露主机名杜绝密钥泄漏endpoint标签取自配置的rpc_url的host部分在 provider 构造时通过url::Url::host_str()提取解析失败则回退为unknown见 sem_evm_rpc_provider.rs。示例Configuredrpc_urlEmittedendpointlabelhttps://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刻意设计URL 的path或query中嵌入的 API Key 不会被发射只有 host 会暴露从而保证 Prometheus 抓取内容不泄露密钥。源码注释明确写到 Only the host is emitted — the URL path (which may contain API keys) is deliberately NOT exposed。典型使用场景对比多个 RPC 供应商Alchemy vs Infura vs 自建节点的延迟与错误率检测供应商级别的故障某个 endpoint 错误率飙升而其他健康在轮换供应商时将信号量饱和归因到具体 endpoint。3.2method标签取值eth_blockNumber、eth_chainId、eth_getBlockByNumber、eth_getBlockByHash、eth_getTransactionReceipt、eth_getBlockReceipts、eth_getTransactionReceipt_batch。3.3error_kind标签取值RPC 层ValueDescriptiondeserialization响应无法反序列化大概率是节点 bug 或 schema 不匹配unsupported_method节点不支持该 RPC 方法rate_limited节点返回 HTTP 429 或限流错误transport网络/连接失败not_found区块或收据返回 nullbatch_error批量请求失败HTTP 错误或解析失败batch_unsupported节点不支持批量 JSON-RPC从 raw_request 的实现可以看到错误分类的具体依据错误信息包含deserialization error/data did not match→deserialization包含does not exist/is not whitelisted/is unsupported→unsupported_method包含rate limit/too many requests/429→rate_limited其余归为transport。每次分类都会调用record_rpc_error()同时递增listener_rpc_requests_total{statuserror}、listener_rpc_errors_total{error_kind...}并记录耗时直方图。not_found与批量相关分类则在批处理路径中产生。四、Broker 指标参考brokercrate 自身发射broker_*前缀的指标完整目录见 metrics.rs主要包括broker_messages_published_totalbroker_publish_errors_totalbroker_publish_duration_secondsbroker_messages_consumed_totalbroker_handler_duration_secondsbroker_circuit_breaker_statebroker_queue_depth_*这些指标与 Listener 指标配套使用broker_queue_depth_*反映各队列积压broker_circuit_breaker_state反映发布链路是否被熔断是排查Listener 正常但下游消费停滞场景的关键。五、Grafana 查询与告警实战PromQL原文档提供了完整的 Grafana 查询示例以下逐条展开并补充使用说明。仓库内置的监控配置可参考 grafana dashboards 与 listener-fleet.jsonPrometheus 采集规则见 prometheus。5.1 同步滞后落后链头区块数listener_chain_height_block_number - listener_db_tip_block_numberGauge 差值的瞬时值即当前落后区块数适合做成 Grafana stat/时间序列面板并叠加阈值告警。5.2 游标停滞告警5 分钟内无迭代rate(listener_cursor_iterations_total[5m]) 0值为1true即表示游标 5 分钟内没有任何迭代Listener 已停摆。这是最高优先级的存活告警。注意结合chain_id标签区分多链实例。5.3 重组织速率每小时increase(listener_reorgs_total[1h])反映所选链每小时的链重组次数。对 PoW/重组频发链此指标可帮助评估是否应启用最终性流程或调整最终性深度。5.4 P99 区块抓取延迟histogram_quantile(0.99, rate(listener_block_fetch_duration_seconds_bucket[5m]))Histogram 桶的_bucket后缀系列配合histogram_quantile得到 P99。若该值持续偏高需要评估 RPC 供应商性能或调高max_concurrent_requests。5.5 RPC 错误率按方法和端点sum by (method, endpoint) (rate(listener_rpc_errors_total[5m]))错误率按method×endpoint二维下钻可快速定位哪个方法在哪个供应商上出错最多。5.6 RPC 延迟按方法和端点P95histogram_quantile(0.95, sum by (method, endpoint, le) (rate(listener_rpc_request_duration_seconds_bucket[5m])))注意必须sum by (method, endpoint, le)保留le标签再计算分位数否则直方图聚合会破坏桶结构。5.7 各端点错误占比对比 RPC 供应商sum by (endpoint) (rate(listener_rpc_errors_total[5m])) / sum by (endpoint) (rate(listener_rpc_requests_total[5m]))错误数除以请求数得到各供应商的错误率直接横向对比 Alchemy / Infura / 自建节点是供应商健康度评分的核心面板。5.8 瞬时错误速率按错误类型sum by (error_kind) (rate(listener_transient_errors_total[5m]))按error_kind分类的瞬时错误速率可识别持续的基础设施故障源如长期block_fetch失败说明某个 RPC 供应商不稳定。5.9 RPC 信号量饱和listener_rpc_semaphore_available 0可用许可为 0 表示所有并发槽位被占满RPC 请求在排队等待。持续饱和说明max_concurrent_requests配置偏低或节点响应过慢。5.10 计算校验失败率按 stallingsum by (stalling) (rate(listener_compute_transaction_failure_total{chain_id$chain_id}[5m]))$chain_id为 Grafana 模板变量按stalling拆分失败率直观区分被跳过的校验失败与导致停摆的校验失败。5.11 任意停摆型计算失败告警候选sum(increase(listener_compute_block_failure_total{stallingtrue}[5m]) increase(listener_compute_transaction_failure_total{stallingtrue}[5m]) increase(listener_compute_receipt_failure_total{stallingtrue}[5m])) by (chain_id) 0三种校验失败区块哈希、交易根、收据根中任何一种以stallingtrue出现且 5 分钟内有增长即触发告警。这是数据完整性受损的直接信号应设为最高严重级别。六、启动初始化为什么所有 Gauge 都要预置 0原文档强调了初始化机制这在源码 init_gauges() 与 init_counters() 中有完整实现所有 Gauge 在启动时置 0listener_db_tip_block_number、listener_chain_height_block_number、listener_final_tip_block_number、listener_final_height_block_number保证 Grafana 在第一次抓取时就发现时间序列即使首个游标迭代尚未完成。计算校验失败计数器按{chain_id, stalling}组合预置 0stallingtrue和stallingfalse各组合都在启动时increment(0)。catchup / finality 相关计数器同样预置 0。原因源码注释原意Prometheus 的increase()/rate()在回看窗口内至少需要两个采样点才能计算差值。如果计数器从不存在直接跳到1increase(...[24h])会报出0——因为没有基线可比。将序列预置为0第一次真实失败就能立即以1呈现在 stat 面板和告警中。对运维实践的启示不要删除预置逻辑也不要在手动注入指标时省掉stallingfalse组合否则该模式下的首次失败会在 24h 窗口类面板中丢失。七、小结一份可落地的监控清单综合以上指标目录生产环境建议至少覆盖以下监控层次存活层rate(listener_cursor_iterations_total[5m]) 0与listener_finality_active 1时的rate(listener_finality_iterations_total[5m]) 0进度层listener_chain_height_block_number - listener_db_tip_block_number同步滞后以及最终性滞后listener_final_height_block_number - listener_final_tip_block_number数据完整性层listener_compute_*_failure_total{stallingtrue}的任一增长供应链listener_publish_errors_total、broker_queue_depth_*、broker_circuit_breaker_stateRPC 依赖层各 endpoint 的错误率与 P95 延迟、listener_rpc_semaphore_available饱和度、listener_transient_errors_total/listener_permanent_errors_total的分类增长后者尤其要即时响应。如需深入指标背后的实现细节可直接阅读 metrics.rs、RPC 封装 sem_evm_rpc_provider.rs 与主循环 evm_listener.rs指标目录的权威列表始终以 metrics.md 为准。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考