fhEVM Coprocessor SQL Exporter：用 Helm + sql_exporter 把 Postgres 指标接入 Prometheus 的完整指南

fhEVM Coprocessor SQL Exporter用 Helm sql_exporter 把 Postgres 指标接入 Prometheus 的完整指南【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读fhEVM 的 Coprocessor 是一个独立于链下运行的计算与中继引擎其状态已发送的交易、未完成的同态计算、待验证的 ZK Proof 等全部持久化在 Postgres 数据库中。charts/coprocessor-sql-exporter是仓库中专门用于观测这套数据库的 Helm Chart它打包了开源项目sql_exporter预置了面向 Coprocessor 核心业务表的 SQL 查询把“数据库里还有多少积压工作”这类关键信号转成 Prometheus 指标。读完本文你将掌握该 Chart 的配置结构、config/queries.yml中每个指标背后的 SQL 逻辑以及如何在 Kubernetes 和本地上快速部署、校验与抓取这些指标。Chart 概览职责与组成charts/coprocessor-sql-exporter本身是一个薄封装 Chartversion 2.0.0核心依赖来自外部仓库的sql-exporter0.17.6apiVersion: v2 name: fhevm-sql-exporter description: A Helm chart for Kubernetes type: application version: 2.0.0 dependencies: - name: sql-exporter repository: https://burningalchemist.github.io/sql_exporter/ version: 0.17.6它共由三个核心文件构成各自职责清晰文件职责Chart.yaml声明 Chart 元信息与外部sql-exporter依赖values.yaml镜像、Secret 注入、ServiceMonitor、ConfigMap 挂载等部署参数config/queries.ymlsql_exporter 的完整配置全局抓取参数、目标数据库连接与全部采集器collector定义其中的关键设计是“配置与部署分离”所有 SQL 采集逻辑都集中在config/queries.yml由模板 templates/configmap.yaml 原样读取并渲染为 ConfigMapapiVersion: v1 kind: ConfigMap metadata: name: coprocessor-sql-exporter-config data: sql_exporter.yml: |- {{ .Files.Get config/queries.yml | indent 4 }}也就是说当你在本机修改config/queries.yml并验证通过后重新helm upgrade即可把新查询带到集群里——这正是 README 中“本地迭代 queries.yml”工作流的最终落点。配置结构详解config/queries.yml全局global与目标target段global: scrape_timeout: 10s scrape_timeout_offset: 500ms min_interval: 0s max_connections: 3 max_idle_connections: 3 target: data_source_name: $DATA_SOURCE_NAME collectors: - coprocessor-databasescrape_timeout/scrape_timeout_offset单次抓取的超时上限为 10s并预留 500ms 偏移量确保在 Prometheus 侧抓取超时前完成查询并返回。max_connections/max_idle_connections对目标 Postgres 的连接池上限与空闲连接数上限均限制为 3。Coprocssor 主服务gw-listener、sns-worker、tx-sender 等本身就重度依赖数据库这里刻意压低连接数避免监控本身抢占业务连接配额。target.data_source_nameDSN 没有硬编码而是引用环境变量$DATA_SOURCE_NAME由 Secret 注入见下文 values.yaml 分析保证密码不落盘在 Chart 中。collectors挂载名为coprocessor-database的采集器。采集器 coprocessor-database六组核心业务指标采集器coprocessor-database设置了min_interval: 30s即每条 SQL 至少每 30 秒才执行一次且受全局scrape_timeout约束对数据库的查询压力可控。六组指标全部为gauge类型围绕 Coprocessor 数据模型中的关键业务表展开1. allowed_handles_txn_sent —— ACL 授权交易积压- metric_name: allowed_handles_txn_sent type: gauge help: Number of allowed handles transactions sent key_labels: - status values: [count] query: | SELECT txn_sent AS status, count(*)::float AS count FROM allowed_handles WHERE txn_is_sent true UNION ALL SELECT txn_unsent AS status, count(*)::float AS count FROM allowed_handles WHERE txn_is_sent false;指标带status标签拆分txn_sent/txn_unsent两个序列。表结构见 20250317140442_create_allow_handle.sqlallowed_handles记录每条 ACL 授权事件event_type0 表示 allow account1 表示 allow public decryptiontxn_is_sent标记对应的允许交易是否已上链txn_retry_count与txn_last_error则用于失败重试追踪。当txn_unsent持续增长时说明 tx-sender 侧发送 ACL 交易出现积压是排队/故障排查的关键信号。迁移 20251230155309_improve_sns_and_txsend_select_indexing.sql 中为allowed_handles (txn_is_sent)建立了索引正是为了让这条计数查询在表变大后依然高效。2. ciphertext_txn_sent —— 密文摘要上链积压- metric_name: ciphertext_txn_sent type: gauge help: Number of ciphertext transactions sent key_labels: - status values: [count] query: | SELECT txn_sent AS status, count(*)::float AS count FROM ciphertext_digest WHERE txn_is_sent true UNION ALL SELECT txn_unsent AS status, count(*)::float AS count FROM ciphertext_digest WHERE txn_is_sent false;ciphertext_digest建表见 20250310120834_create_ciphertext_digest.sql存放密文摘要ciphertext64/ciphertext128两个版本字段txn_is_sent标记摘要交易是否已上链。该指标与allowed_handles_txn_sent结构完全对称用于监控密文上链环节的健康度。迁移 20251203140023_ciphertext_digest_idx_sent_and_handle.sql 建立了(txn_is_sent, created_at)索引同样是为这类“按未发送状态计数”的查询服务。3. computations_completion —— 同态计算完成度- metric_name: computations_completion type: gauge help: Number of computations done key_labels: - status values: [count] query: | SELECT completed AS status, COUNT(*)::float AS count FROM computations WHERE is_completed true UNION ALL SELECT uncompleted AS status, COUNT(*)::float AS count FROM computations WHERE is_completed false;computations是 Coprocessor 最核心的任务表之一建表见 20240722111257_coprocessor.sql记录每次同态运算output_handle、fhe_operation操作类型、dependencies依赖句柄数组、is_scalar、is_completed、is_error等字段主键为(tenant_id, output_handle)。uncompleted数量是判断计算积压的最直接指标——该值长期高企意味着 tfhe-worker / zkproof-worker 处理能力不足或调度出现问题。迁移脚本对该表围绕is_completed、is_error、dependence_chain_id、created_at建立了多组部分索引见 20260120102002_unused_index_cleaning.sql 中的索引清单说明“未完成计算”的筛选是生产环境的高频查询路径。4. pbs_completion —— PBS 计算完成度- metric_name: pbs_completion type: gauge help: Number of PBS done key_labels: - status values: [count] query: | SELECT completed AS status, COUNT(*)::float AS count FROM pbs_computations WHERE is_completed true UNION ALL SELECT uncompleted AS status, COUNT(*)::float AS count FROM pbs_computations WHERE is_completed false;pbs_computations建表见 20250205130209_create_pbs_computations_table.sql与computations结构相似但更精简handle、created_at、completed_at、is_completed用于追踪 Programmable BootstrapPBS类操作的状态。uncompleted序列可以单独告警帮助区分 PBS 密集场景下的负载特征。5. ciphertexts —— 密文总量- metric_name: ciphertexts type: gauge help: Number of ciphertexts in ciphertexts table values: [count] query: | SELECT COUNT(*)::float AS count FROM ciphertexts;直接统计ciphertexts表建表见 20240722111257_coprocessor.sql的总行数。该表主键为(tenant_id, handle, ciphertext_version)保存每个密文句柄对应的实际密文内容。此指标反映数据库的数据规模与增长速度可用于容量规划由于是全表计数在数据量大时其耗时也可能成为 scrape 的瓶颈。6. zkproof —— ZK Proof 待处理量- metric_name: zkproof type: gauge help: Number of remaining ZK-Proof to process values: [count] query: | SELECT COUNT(*)::float AS count FROM verify_proofs;统计verify_proofs表建表见 20250207092623_verify_proofs.sql的全部行数。该表记录待验证的 ZK Proofzk_proof_id、chain_id、contract_address、user_address、input、handles、verified三态NULL 未验证 / true / false、retry_count、last_error等。表上的索引idx_verify_proofs_verified_retry (verified, retry_count, zk_proof_id)表明系统按“验证状态 重试次数”的顺序消费任务。该指标的上升意味着 zkproof-worker 存在积压是链上验证能力是否跟得上的直接证据。指标背后的数据模型小结指标查询表核心字段监控含义allowed_handles_txn_sentallowed_handlestxn_is_sentACL 授权交易上链积压ciphertext_txn_sentciphertext_digesttxn_is_sent密文摘要上链积压computations_completioncomputationsis_completed同态计算任务积压pbs_completionpbs_computationsis_completedPBS 计算任务积压ciphertextsciphertexts行数密文存储规模zkproofverify_proofs行数ZK Proof 待验证积压values.yaml部署参数的逐项说明values.yaml 覆盖了镜像、凭据注入、监控抓取与配置挂载四个方面sql-exporter: replicaCount: 1 image: repository: hub.zama.org/zama-protocol/zama.ai/sql_exporter tag: 0.23.0 imagePullSecrets: - name: registry-credentials serviceMonitor: enabled: true interval: 30s # Disable inline config; we provide /etc/sql_exporter/sql_exporter.yml from # the ConfigMap rendered by templates/configmap.yaml. createConfig: false env: DATA_SOURCE_NAME: from: kind: Secret name: sql-exporter-config key: DATA_SOURCE_NAME extraVolumes: - name: sql-exporter-config volume: configMap: name: coprocessor-sql-exporter-config mount: readOnly: true mountPath: /etc/sql_exporter/sql_exporter.yml subPath: sql_exporter.yml关键点镜像与拉取使用 Zama 内部镜像仓库hub.zama.org/zama-protocol/zama.ai/sql_exporter:0.23.0并通过imagePullSecrets: registry-credentials完成私有仓库鉴权。若你的集群可直连公共 Docker Hub可将其替换为burningalchemist/sql_exporter对应版本。ServiceMonitorenabled: true且抓取间隔30s与采集器min_interval保持一致说明该 Chart 面向 Prometheus Operator 生态安装后会自动生成 ServiceMonitor 供 Prometheus 发现。createConfig: false关闭依赖 Chart 自带的内联配置改用下方 ConfigMap 提供的完整配置保证配置源唯一即仓库中的config/queries.yml。env.DATA_SOURCE_NAME从 Secretsql-exporter-config的DATA_SOURCE_NAME键注入连接串对应config/queries.yml中的$DATA_SOURCE_NAME占位符。extraVolumes把 ConfigMapcoprocessor-sql-exporter-config以readOnly方式挂载到容器内/etc/sql_exporter/sql_exporter.ymlsubPath只挂载其中sql_exporter.yml一个键即 sql_exporter 默认读取的配置路径。在 Kubernetes 中安装第一步创建数据库连接 Secret在发布命名空间示例为coprocessor中先创建保存 DSN 的 Secret。README 给出的写法同时使用--dry-run与管道kubectl apply实现“先本地生成、再幂等应用”避免密码出现在 shell 历史之外的明文文件里kubectl -n coprocessor create secret generic sql-exporter-config \ --from-literalDATA_SOURCE_NAMEpostgres://coprocessor:passwordhost:5432/coprocessor \ --dry-runclient -o yaml | kubectl apply -f -Secret 名称sql-exporter-config与键名DATA_SOURCE_NAME必须与 values.yaml 中env段的引用完全一致。若数据库凭据后续轮换只需重新 apply 该 Secret 并重启 Pod或触发 rollout无需改动 Chart。第二步拉取依赖并安装helm dependency update helm upgrade --install fhevm-sql-exporter . -n coprocessorhelm dependency update会把Chart.yaml声明的外部依赖sql-exporter 0.17.6下载到charts/目录首次安装或升级依赖前必须执行helm upgrade --install同时覆盖首次安装与后续升级场景命名fhevm-sql-exporter目标命名空间coprocessor。第三步验证抓取安装完成后通过 ServiceMonitorinterval: 30sPrometheus 会自动发现并抓取该 exporter。也可以在集群内直接验证指标端点是否存活kubectl -n coprocessor port-forward svc/sql-exporter-service 9399:9399 curl -s localhost:9399/metrics | grep -E allowed_handles_txn_sent|computations_completion|zkproof本地运行与配置迭代config/queries.yml在集群与本地共用同一份因此可以完全在本地迭代 SQL、验证语法再通过helm upgrade推送回集群。校验配置语法无需数据库sql_exporter -config.file config/queries.yml -config.check该命令会解析 YAML 并解析 collector 引用但不会连接 Postgres因此此时不需要设置任何数据库环境变量。它是 CI 或本地改动后最快的第一道防线——能够尽早发现 YAML 缩进错误、metric 定义缺失等低级问题。连接真实数据库抓取当需要验证 SQL 本身表名、字段、类型转换是否正确时指向一个可达的 Postgres 实例export DATA_SOURCE_NAMEpostgres://coprocessor:$DATABASE_PASSWORDlocalhost:5432/coprocessor sql_exporter -config.file config/queries.yml curl -s localhost:9399/metrics默认监听端口为9399这是 sql_exporter 的默认 metrics 端口这里连接串使用了$DATABASE_PASSWORD变量注意 shell 单引号内不会展开需提前 export与 Kubernetes 环境通过 Secret 注入的方式对应curl -s localhost:9399/metrics输出中应能看到allowed_handles_txn_sent{statustxn_sent}、zkproof等以fhevm_之外原始名称暴露的指标实际名称即config/queries.yml中的metric_name。README 特别提示sql_exporter二进制本身来自开源项目 burningalchemist/sql_exporter 的 release 页面与 Chart 依赖的镜像版本0.23.0配套使用即可。运维建议如何用这些指标做告警综合config/queries.yml的采集逻辑与 db-migration 中对应的表结构可以给出以下可落地的监控口径均为基于源码结构的推断建议阈值需按实际负载标定上链积压告警对allowed_handles_txn_sent{statustxn_unsent}与ciphertext_txn_sent{statustxn_unsent}设置持续增长告警反映 tx-sender / sns-worker 发送交易滞后。计算积压告警对computations_completion{statusuncompleted}与pbs_completion{statusuncompleted}设置水位告警反映 tfhe-worker 处理能力不足。ZK 验证积压告警对zkproof设置阈值告警结合verify_proofs表中verified三态与retry_count的索引设计可在积压时进一步下钻查询具体失败原因。容量与性能ciphertexts总量用于容量规划若 scrape 耗时接近scrape_timeout: 10s说明全表计数类查询开销过大需考虑按 tenant 拆分或引入预聚合。小结charts/coprocessor-sql-exporter通过“外部 sql-exporter 依赖 自管 ConfigMap 配置 Secret 注入 DSN ServiceMonitor 接入”的组合为 fhEVM Coprocessor 的 Postgres 数据库提供了一套开箱即用的 Prometheus 可观测性方案。其价值在于六组指标精准对应当前仓库数据库迁移中真实存在的computations、pbs_computations、ciphertexts、ciphertext_digest、allowed_handles、verify_proofs表让“计算积压、上链积压、ZK 积压”这些 Coprocessor 的核心健康信号可以直接进入告警与看板体系而无需为监控编写额外的业务逻辑。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考