fhevm Relayer 链上交易指标体系监控在途交易、延迟与错误率的完整指南【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读本指南围绕 fhevm 仓库中 relayer/src/metrics/docs_and_dashboards/transactions.md 展开系统讲解 Relayer 与区块链EVM交互过程中的交易级可观测性设计包括 4 个核心 Prometheus 指标的定义与标签、它们在 交易引擎与发送链路 中的实际埋点调用以及 3 个可直接落地的 Grafana 面板与 PromQL 查询。读完本文你将掌握如何通过这套指标定位卡死的交易stuck transaction、RPC 不稳定、nonce 冲突以及重试耗尽后被丢弃的关键失败并在 Grafana 中搭建对应的监控视图。1. 为什么需要专门的链上交易指标Relayer 的核心职责之一是把input_request密文输入、user_decrypt_request用户解密、public_decrypt_request公开解密等请求以交易形式提交到 EVM 链上。与普通的 HTTP 服务监控不同链上交易的生命周期跨越多个阶段进入交易引擎、gas 估算、RPC 发送、内存池mempool等待、出块确认或最终失败。任何一环出问题都会表现为用户请求迟迟得不到结果且症状与根因之间往往隔着多层间接关系。原文档明确列出了该指标体系要解决的三大类问题卡死的交易stuck transactions交易长时间停留在 mempool 或重试队列中RPC 不稳定网络连接或节点 HTTP 层面的抖动重试耗尽后的关键失败引擎彻底放弃某笔交易这类失败被标记为CRITICAL。对应的指标实现在 relayer/src/metrics/transaction.rs 中通过TransactionMetrics结构体统一持有四个指标并在 startup.rs 启动阶段由init_transaction_metrics注册到 Prometheus registry随后经 metrics/server.rs 的/metrics端点暴露。2. 四个核心指标的规格说明2.1 Gauge在途交易数relayer_transaction_pending_gauge项值类型GaugeVec描述当前正在被处理的链上交易数量处于 mempool、模拟或重试中标签transaction_typeinput_request、user_decrypt_request、public_decrypt_request该指标反映交易管理器transaction manager当前承受的瞬时负载。它在源码中的生命周期如下transaction.rstransaction_broadcast()发送流程开始时对对应transaction_type的 gauge 执行inc()transaction_claim_lost()若发送被跳过行锁 claim 未生效执行dec()平衡 gaugetransaction_confirmed()/transaction_failure()/transaction_receipt_refused()交易终结时均会dec()。也就是说gauge 的入账与出账严格配对任何一个终结路径都不会漏减因此该指标应保持平稳而非单调增长。2.2 Counter交易量与最终状态relayer_transaction_count项值类型CounterVec描述已处理交易总数按最终状态确认/失败分类标签transaction_typeinput_request、user_decrypt_request、public_decrypt_requesttransaction_statusconfirmed、failed该指标在transaction_confirmed()与transaction_failure()中分别以confirmed/failed标签累加。需要特别指出的是源码中的状态枚举比原文档多出一个receipt_refused分支transaction.rs当交易确实在链上落地、但回执因 epoch fence 被拒本 Pod 未写入该行通常由后继者接管会调用transaction_receipt_refused()单独计数——它既不算成功也不算失败用于区分链上已生效但本实例未持久化这一特殊状态。2.3 Histogram提交延迟relayer_transaction_duration_secs项值类型HistogramVec描述从提交开始到最终确认或失败的耗时单位秒float源码内部由毫秒除以 1000 换算分桶默认[0.01, 0.1, 0.25, 0.50, 0.75, 1.0, 1.25, 1.5, 2.0, 5.0, 10.0]秒标签transaction_type、statusconfirmed/failed/receipt_refused分桶并非写死在代码里而是通过 MetricsConfig.transaction_duration_secs_histogram_bucket 配置注入支持Vecf64或映射两种反序列化格式。测试配置 relayer-test-config.yaml 中的默认值如上表所示从 10ms 起步、覆盖到 10s兼顾了正常出块延迟与异常长尾。2.4 Counter错误细分relayer_transaction_errors_total项值类型CounterVec描述交易生命周期中遇到的具体错误计数同一笔交易可能累加多次例如成功前经历 3 次 nonce 错误标签error_type另有revert_category、request_type两个增强标签见下文原文档列出的error_type取值及含义如下error_type含义严重度max_retries_exceeded引擎彻底放弃该交易gas 估算或发送重试耗尽CRITICAL应触发告警nonce_error账户序号nonce不匹配通常暗示同步问题transport_error网络连接或 HTTP 层问题通常指向 RPC 节点故障rpc_errorEVM 执行回滚或节点内部错误非 nonce 类reverted交易因合约 revert 而失败invalid_address地址格式错误 / 目标合约地址无效unknown_error交易引擎尚未归类的错误结合源码 transaction.rs实际枚举还包含原文档未提及的reverted_acl_selectorACL 选择器触发的 revert且track_engine_error_with_label()签名带有revert_category与request_type两个可选标签transaction.rs调用时未传则分别回退为空字符串和unknown。此外源码预定义了 5 个 revert 原因标签常量transaction.rsinsufficient_balance、insufficient_allowance、contract_paused、invalid_signature、unknown并由track_revert_with_request_type()从网关层on_failure钩子注入用于按业务原因精细化告警。3. 指标在源码中的埋点调用链理解指标不能只看定义还要知道它们在什么时机被触发。核心调用路径集中在两处3.1 发送主流程send_raw_transaction_synchelper.rs 中的send_raw_transaction_sync是完整的生命周期编排transaction_broadcast()gaugeinc()标记一笔在途交易开始hook.on_tx_in_flight()抢占行锁若ClaimLost调用transaction_claim_lost()平衡 gauge 并直接返回这是良性结果不计数、不计延迟tx_engine.prepare_transaction()失败 →transaction_failure()记录failed与耗时send_raw_transaction_sync_with_retries()失败 →transaction_failure()返回GateClosed时保持行状态交由后继 sweep 处理收到回执后hook.on_receipt_received()Recorded→transaction_confirmed()Refused→transaction_receipt_refused()。每一次终结路径都同时完成三件事gauge 递减、counter 按状态累加、histogram 记录耗时transaction.rs。3.2 错误分类埋点错误细分指标在 engine.rs 中按场景触发prepare_transaction中检查目标地址无合约代码时上报InvalidAddressengine.rsgas 估算重试次数达到gas_estimation_max_retries时上报MaxRetriesExceededengine.rs发送重试循环中分别针对Nonce、Rpc、Transport、Unknown打点engine.rs。这与 transaction.rs 顶部注释中的设计 TODO 一一对应统计 max retries 后的失败状态、nonce 错误、transport 错误、非 nonce 的 RPC 错误并跟踪成功/失败响应数。4. Grafana 仪表盘面板与 PromQL 查询原文档配套了 3 个可直接复用的 Grafana 面板。以下查询均基于默认 label 命名若你自定义了指标名需同步调整。4.1 面板一按类型拆分错误Error Breakdown by Type可视化类型Time Series堆叠用途展示各类错误的发生速率。高nonce_error表明账户同步异常高transport_error指向 RPC 节点问题。PromQLsum by (error_type) (increase(relayer_transaction_errors_total[$__range]))需要注意由于relayer_transaction_errors_total实际带有revert_category、request_type两个额外标签直接对全量序列求和会混合所有类别。若希望单独观察某类请求或某个 revert 原因可先用error_type与request_type精确匹配例如sum by (error_type) (increase(relayer_transaction_errors_total{request_typeuser_decrypt_request}[$__range]))4.2 面板二交易延迟 P95Transaction Latency P95可视化类型Time Series用途展示交易被打包上链的耗时第 95 百分位单位秒。PromQLhistogram_quantile(0.95, sum by (le, transaction_type) ( rate(relayer_transaction_duration_secs[5m]) ))由于 histogram 带有status标签sum by (le, transaction_type)会跨状态聚合。若要区分确认与失败路径的延迟可在sum前用{statusconfirmed}过滤。4.3 面板三在途交易In-Flight Transactions可视化类型Stat / Gauge用途展示交易管理器当前积压量Mempool Retries不应单调增长一旦持续爬升即意味着交易堆积或节点异常。PromQLsum by (transaction_type) (relayer_transaction_pending_gauge)5. 告警建议与最佳实践结合原文档的严重度标注与源码实现建议优先配置以下告警CRITICALrate(relayer_transaction_errors_total{error_typemax_retries_exceeded}[5m]) 0—— 引擎已放弃交易代表用户请求必然失败需要立即介入WARNINGrelayer_transaction_pending_gauge持续上升例如 5 分钟内增长超过阈值—— 交易卡在 mempool 或重试队列WARNINGrate(relayer_transaction_errors_total{error_typenonce_error}[5m])突增 —— 账户 nonce 同步异常通常是并发发送或节点状态不一致WARNINGrate(relayer_transaction_errors_total{error_typetransport_error}[5m])突增 —— RPC 节点连接不稳定。指标暴露与配置前提交易指标随 Relayer 启动自动注册startup.rs通过metrics.endpoint配置的地址如0.0.0.0:9898以 Prometheus 文本格式暴露历史分桶可通过 MetricsConfig 调整无需改动代码。6. 小结relayer_transaction_pending_gauge、relayer_transaction_count、relayer_transaction_duration_secs、relayer_transaction_errors_total四个指标共同构成了 fhevm Relayer 链上交易的完整可观测闭环gauge 看积压、counter 看吞吐与成败、histogram 看延迟分布、错误 counter 看根因归类。结合本指南的 PromQL 面板与告警规则你可以快速区分交易卡住RPC 故障nonce 冲突与重试耗尽等不同故障形态并依据 transaction.rs 中的扩展标签revert_category、request_type、receipt_refused进一步下钻定位。更深入的发送重试策略与GateClosed等状态语义可继续阅读 engine.rs 与 helper.rs。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 fhevm Relayer 链上交易指标体系：监控在途交易、延迟与错误率的完整指南
fhevm Relayer 链上交易指标体系监控在途交易、延迟与错误率的完整指南【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读本指南围绕 fhevm 仓库中 relayer/src/metrics/docs_and_dashboards/transactions.md 展开系统讲解 Relayer 与区块链EVM交互过程中的交易级可观测性设计包括 4 个核心 Prometheus 指标的定义与标签、它们在 交易引擎与发送链路 中的实际埋点调用以及 3 个可直接落地的 Grafana 面板与 PromQL 查询。读完本文你将掌握如何通过这套指标定位卡死的交易stuck transaction、RPC 不稳定、nonce 冲突以及重试耗尽后被丢弃的关键失败并在 Grafana 中搭建对应的监控视图。1. 为什么需要专门的链上交易指标Relayer 的核心职责之一是把input_request密文输入、user_decrypt_request用户解密、public_decrypt_request公开解密等请求以交易形式提交到 EVM 链上。与普通的 HTTP 服务监控不同链上交易的生命周期跨越多个阶段进入交易引擎、gas 估算、RPC 发送、内存池mempool等待、出块确认或最终失败。任何一环出问题都会表现为用户请求迟迟得不到结果且症状与根因之间往往隔着多层间接关系。原文档明确列出了该指标体系要解决的三大类问题卡死的交易stuck transactions交易长时间停留在 mempool 或重试队列中RPC 不稳定网络连接或节点 HTTP 层面的抖动重试耗尽后的关键失败引擎彻底放弃某笔交易这类失败被标记为CRITICAL。对应的指标实现在 relayer/src/metrics/transaction.rs 中通过TransactionMetrics结构体统一持有四个指标并在 startup.rs 启动阶段由init_transaction_metrics注册到 Prometheus registry随后经 metrics/server.rs 的/metrics端点暴露。2. 四个核心指标的规格说明2.1 Gauge在途交易数relayer_transaction_pending_gauge项值类型GaugeVec描述当前正在被处理的链上交易数量处于 mempool、模拟或重试中标签transaction_typeinput_request、user_decrypt_request、public_decrypt_request该指标反映交易管理器transaction manager当前承受的瞬时负载。它在源码中的生命周期如下transaction.rstransaction_broadcast()发送流程开始时对对应transaction_type的 gauge 执行inc()transaction_claim_lost()若发送被跳过行锁 claim 未生效执行dec()平衡 gaugetransaction_confirmed()/transaction_failure()/transaction_receipt_refused()交易终结时均会dec()。也就是说gauge 的入账与出账严格配对任何一个终结路径都不会漏减因此该指标应保持平稳而非单调增长。2.2 Counter交易量与最终状态relayer_transaction_count项值类型CounterVec描述已处理交易总数按最终状态确认/失败分类标签transaction_typeinput_request、user_decrypt_request、public_decrypt_requesttransaction_statusconfirmed、failed该指标在transaction_confirmed()与transaction_failure()中分别以confirmed/failed标签累加。需要特别指出的是源码中的状态枚举比原文档多出一个receipt_refused分支transaction.rs当交易确实在链上落地、但回执因 epoch fence 被拒本 Pod 未写入该行通常由后继者接管会调用transaction_receipt_refused()单独计数——它既不算成功也不算失败用于区分链上已生效但本实例未持久化这一特殊状态。2.3 Histogram提交延迟relayer_transaction_duration_secs项值类型HistogramVec描述从提交开始到最终确认或失败的耗时单位秒float源码内部由毫秒除以 1000 换算分桶默认[0.01, 0.1, 0.25, 0.50, 0.75, 1.0, 1.25, 1.5, 2.0, 5.0, 10.0]秒标签transaction_type、statusconfirmed/failed/receipt_refused分桶并非写死在代码里而是通过 MetricsConfig.transaction_duration_secs_histogram_bucket 配置注入支持Vecf64或映射两种反序列化格式。测试配置 relayer-test-config.yaml 中的默认值如上表所示从 10ms 起步、覆盖到 10s兼顾了正常出块延迟与异常长尾。2.4 Counter错误细分relayer_transaction_errors_total项值类型CounterVec描述交易生命周期中遇到的具体错误计数同一笔交易可能累加多次例如成功前经历 3 次 nonce 错误标签error_type另有revert_category、request_type两个增强标签见下文原文档列出的error_type取值及含义如下error_type含义严重度max_retries_exceeded引擎彻底放弃该交易gas 估算或发送重试耗尽CRITICAL应触发告警nonce_error账户序号nonce不匹配通常暗示同步问题transport_error网络连接或 HTTP 层问题通常指向 RPC 节点故障rpc_errorEVM 执行回滚或节点内部错误非 nonce 类reverted交易因合约 revert 而失败invalid_address地址格式错误 / 目标合约地址无效unknown_error交易引擎尚未归类的错误结合源码 transaction.rs实际枚举还包含原文档未提及的reverted_acl_selectorACL 选择器触发的 revert且track_engine_error_with_label()签名带有revert_category与request_type两个可选标签transaction.rs调用时未传则分别回退为空字符串和unknown。此外源码预定义了 5 个 revert 原因标签常量transaction.rsinsufficient_balance、insufficient_allowance、contract_paused、invalid_signature、unknown并由track_revert_with_request_type()从网关层on_failure钩子注入用于按业务原因精细化告警。3. 指标在源码中的埋点调用链理解指标不能只看定义还要知道它们在什么时机被触发。核心调用路径集中在两处3.1 发送主流程send_raw_transaction_synchelper.rs 中的send_raw_transaction_sync是完整的生命周期编排transaction_broadcast()gaugeinc()标记一笔在途交易开始hook.on_tx_in_flight()抢占行锁若ClaimLost调用transaction_claim_lost()平衡 gauge 并直接返回这是良性结果不计数、不计延迟tx_engine.prepare_transaction()失败 →transaction_failure()记录failed与耗时send_raw_transaction_sync_with_retries()失败 →transaction_failure()返回GateClosed时保持行状态交由后继 sweep 处理收到回执后hook.on_receipt_received()Recorded→transaction_confirmed()Refused→transaction_receipt_refused()。每一次终结路径都同时完成三件事gauge 递减、counter 按状态累加、histogram 记录耗时transaction.rs。3.2 错误分类埋点错误细分指标在 engine.rs 中按场景触发prepare_transaction中检查目标地址无合约代码时上报InvalidAddressengine.rsgas 估算重试次数达到gas_estimation_max_retries时上报MaxRetriesExceededengine.rs发送重试循环中分别针对Nonce、Rpc、Transport、Unknown打点engine.rs。这与 transaction.rs 顶部注释中的设计 TODO 一一对应统计 max retries 后的失败状态、nonce 错误、transport 错误、非 nonce 的 RPC 错误并跟踪成功/失败响应数。4. Grafana 仪表盘面板与 PromQL 查询原文档配套了 3 个可直接复用的 Grafana 面板。以下查询均基于默认 label 命名若你自定义了指标名需同步调整。4.1 面板一按类型拆分错误Error Breakdown by Type可视化类型Time Series堆叠用途展示各类错误的发生速率。高nonce_error表明账户同步异常高transport_error指向 RPC 节点问题。PromQLsum by (error_type) (increase(relayer_transaction_errors_total[$__range]))需要注意由于relayer_transaction_errors_total实际带有revert_category、request_type两个额外标签直接对全量序列求和会混合所有类别。若希望单独观察某类请求或某个 revert 原因可先用error_type与request_type精确匹配例如sum by (error_type) (increase(relayer_transaction_errors_total{request_typeuser_decrypt_request}[$__range]))4.2 面板二交易延迟 P95Transaction Latency P95可视化类型Time Series用途展示交易被打包上链的耗时第 95 百分位单位秒。PromQLhistogram_quantile(0.95, sum by (le, transaction_type) ( rate(relayer_transaction_duration_secs[5m]) ))由于 histogram 带有status标签sum by (le, transaction_type)会跨状态聚合。若要区分确认与失败路径的延迟可在sum前用{statusconfirmed}过滤。4.3 面板三在途交易In-Flight Transactions可视化类型Stat / Gauge用途展示交易管理器当前积压量Mempool Retries不应单调增长一旦持续爬升即意味着交易堆积或节点异常。PromQLsum by (transaction_type) (relayer_transaction_pending_gauge)5. 告警建议与最佳实践结合原文档的严重度标注与源码实现建议优先配置以下告警CRITICALrate(relayer_transaction_errors_total{error_typemax_retries_exceeded}[5m]) 0—— 引擎已放弃交易代表用户请求必然失败需要立即介入WARNINGrelayer_transaction_pending_gauge持续上升例如 5 分钟内增长超过阈值—— 交易卡在 mempool 或重试队列WARNINGrate(relayer_transaction_errors_total{error_typenonce_error}[5m])突增 —— 账户 nonce 同步异常通常是并发发送或节点状态不一致WARNINGrate(relayer_transaction_errors_total{error_typetransport_error}[5m])突增 —— RPC 节点连接不稳定。指标暴露与配置前提交易指标随 Relayer 启动自动注册startup.rs通过metrics.endpoint配置的地址如0.0.0.0:9898以 Prometheus 文本格式暴露历史分桶可通过 MetricsConfig 调整无需改动代码。6. 小结relayer_transaction_pending_gauge、relayer_transaction_count、relayer_transaction_duration_secs、relayer_transaction_errors_total四个指标共同构成了 fhevm Relayer 链上交易的完整可观测闭环gauge 看积压、counter 看吞吐与成败、histogram 看延迟分布、错误 counter 看根因归类。结合本指南的 PromQL 面板与告警规则你可以快速区分交易卡住RPC 故障nonce 冲突与重试耗尽等不同故障形态并依据 transaction.rs 中的扩展标签revert_category、request_type、receipt_refused进一步下钻定位。更深入的发送重试策略与GateClosed等状态语义可继续阅读 engine.rs 与 helper.rs。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考