数据库可观测性运维【免费下载链接】pgheroA performance dashboard for Postgres项目地址https://gitcode.com/gh_mirrors/pg/pghero点击查看免费下载本文面向希望为 PgHero 贡献代码、调试其源码或深入理解其工作原理的开发者基于仓库中 guides/Contributing.md 的官方开发指引展开并结合本仓库的生成器、Rake 任务与配置模板源码完整还原从克隆代码、准备开发数据库、生成统计表结构到启动本地仪表盘的全部流程。读完本文你将能独立搭建一套可运行、可调试、可测试的 PgHero 开发环境并理解其背后的 Rails Engine 机制、历史统计数据的存储模型与配置体系。开发环境概览你需要准备什么PgHero 是一个以 Rails Engine 形式分发见 lib/pghero/engine.rb的 PostgreSQL 性能仪表盘 Gem。因此开发它的本地环境本质上就是一个宿主 Rails 应用 挂载 PgHero 引擎的组合。Contributing 文档给出了两条并行的准备路径本机需要一个可用的 PostgreSQL 服务用于承载开发用数据库与 PgHero 的历史统计表需要 Ruby 与 Bundler 环境因为 PgHero 的 Gemfile、Gemfile.lock 依赖解析、Rake 任务与 Rails Generator 都依赖 Ruby 生态。从仓库维护情况看PgHero 持续跟进最新的 ActiveRecord 版本——gemfiles/activerecord72.gemfile 与 gemfiles/activerecord80.gemfile 分别对应 ActiveRecord 7.2 与 8.0 的测试矩阵贡献者在选择 Ruby/Rails 版本时可参考这两个 Gemfile 的目标版本。第一步克隆代码仓库Contributing 文档给出的克隆命令如下git clone https://github.com/ankane/pghero.git git clone https://github.com/pghero/pghero.git pghero-dev cd pghero-dev git checkout dev这里有两个值得注意的细节第一个git clone得到的是PgHero 主线仓库用于阅读最新源码与提交记录第二个git clone得到的是PgHero 的 dev 分支开发仓库并显式git checkout dev。开发仓库与主线仓库的目录是分开的后者名为pghero-dev这样在开发机上可以在两个工作区之间自由对照、打补丁与运行测试而不互相干扰。克隆完成后进入pghero-dev目录后续所有命令都在该目录下执行。需要说明的是dev分支是 PgHero 面向贡献者开放的活跃开发分支日常修改建议在此分支上基于dev拉出功能分支进行。第二步创建开发数据库createdb pghero_dev export DATABASE_URLpostgres:///pghero_devcreatedb pghero_dev通过本地 PostgreSQL 创建一个名为pghero_dev的空数据库。随后通过环境变量DATABASE_URL告诉 PgHero 开发应用连接哪个数据库。这里使用postgres:///pghero_dev这种省略主机名的 URL 形式表示走 Unix 域套接字连接本机默认用户下的同名数据库。DATABASE_URL是贯穿整个 PgHero 使用与开发流程的核心环境变量。在 PgHero 中数据库的解析优先级为config/pghero.yml中显式声明的databases配置PGHERO_DATABASE_URL环境变量Rails 应用自身的database.yml配置。从 lib/pghero.rb 的default_config实现可以看到在没有PGHERO_DATABASE_URL时PgHero 会遍历ActiveRecord::Base.configurations中当前环境的所有数据库配置若最终为空才回退到PGHERO_DATABASE_URL指定的单一primary数据库。因此DATABASE_URL这条 export 确保了开发模式下数据库连接明确、可控。提示export只在当前 Shell 会话内生效重新开终端后需要再次执行。也可以用.env文件配合 dotenv 类工具管理但 Contributing 文档本身只要求这一条 export。第三步生成统计表并执行迁移bundle exec rails generate pghero:query_stats bundle exec rails generate pghero:space_stats bundle exec rails db:migrate这三条命令是开发环境初始化的核心前两条通过 Rails Generator 把 PgHero 的历史统计表结构模板复制进宿主应用的db/migrate目录第三条把它们真正写入pghero_dev数据库。生成器query_stats 与 space_stats对应生成器源码位于 lib/generators/pghero/query_stats_generator.rb 与 lib/generators/pghero/space_stats_generator.rb。它们继承Rails::Generators::Base并混入ActiveRecord::Generators::Migration通过migration_template将模板渲染为带版本号前缀的迁移文件query_stats_generator生成db/migrate/create_pghero_query_stats.rbspace_stats_generator生成db/migrate/create_pghero_space_stats.rb生成的迁移文件名由migration_version方法拼接当前 ActiveRecord 主次版本如[8.0]确保迁移与宿主应用所依赖的 ActiveRecord 大版本一致。历史查询统计表结构rails generate pghero:query_stats生成的迁移模板见 lib/generators/pghero/templates/query_stats.rb.tt包含两张表表字段说明pghero_queriesquerytext hash 索引去重存储被采集的 SQL 原文pghero_query_statsdatabase、user、query_id、query_hash8 字节整数、total_timefloat、calls8 字节整数、captured_attimestamp每次采集快照的聚合指标其中query字段使用using: :hash索引因为查询原文可能很长hash 索引能高效支撑等值匹配pghero_query_stats上建有[:database, :captured_at]复合索引服务于按数据库 时间范围的统计查询query_id通过t.references :query, index: false关联pghero_queries外键索引故意不建减少写入开销。历史空间统计表结构rails generate pghero:space_stats生成的迁移模板见 lib/generators/pghero/templates/space_stats.rb.tt创建单张表pghero_space_stats字段说明database数据库标识schema表所在 schemarelation表/物化视图/索引名size8 字节整数字节数captured_at采集时间戳同样带有[:database, :captured_at]复合索引。这张表支撑了 PgHero 仪表盘上 Space空间页面的历史趋势展示对应 lib/pghero/methods/space.rb 中space_growth等方法对pghero_space_stats的聚合查询。迁移与模型层的对接bundle exec rails db:migrate执行后PgHero 通过 ActiveRecord 模型读写这些表。模型定义在 lib/pghero/query_stats.rbPgHero::QueryStatstable_name pghero_query_stats与 lib/pghero/space_stats.rbPgHero::SpaceStatstable_name pghero_space_stats。值得留意的是 lib/pghero/query_stats.rb 中的注释模型刻意不声明belongs_to :query因为这会破坏历史数据回填流程——旧版本数据中query列尚未拆分到pghero_queries表时的兼容逻辑依赖这一点。对于从旧版本升级的开发场景仓库还提供了第三个生成器pghero:upgrade_query_stats见 lib/generators/pghero/upgrade_query_stats_generator.rb其迁移模板 upgrade_query_stats.rb.tt 会为pghero_query_stats新增query_id引用列把pghero_query_stats.query中不同的原文批量写入pghero_queries用UPDATE ... FROM关联回填query_id后删除query列。这解释了为什么pghero_queries与pghero_query_stats需要拆成两张表查询原文只需存一份统计快照只保留query_id引用与聚合数值从而大幅压缩历史数据的存储体积。第四步启动开发服务器foreman startforeman是一个进程管理器它会读取项目根目录的Procfile并按其中定义的进程组同时启动开发服务。PgHero 开发环境中默认启动的就是宿主 Rails 应用即挂载了 PgHero 引擎的开发版仪表盘。然后访问http://localhost:50005000是foreman的默认端口PORT默认值Contributing 文档明确以该端口作为本地访问入口。如果 5000 被占用可以设置PORT环境变量切换端口。仪表盘路由速览开发服务器启动后挂载的 PgHero 引擎路由由 config/routes.rb 定义常用入口包括路径功能/仪表盘首页overview/space、/space/:relation空间占用与单个关系详情/index_bloat索引膨胀分析/live_queries实时查询监控/queries、/queries/:query_hash慢查询统计与单查询历史/system、/cpu_usage等系统指标配合 AWS/GCP/explain执行计划分析/tune配置建议/connections、/maintenance连接与维护操作POST/kill、/kill_all等终止查询/连接POST/enable_query_stats、/reset_query_stats开关/重置统计路由还保留了两个旧地址的 301 重定向/system_stats→/system、/query_stats→/queries。开发者在新增页面时需遵循同样的命名习惯。理解配置体系contributor 必读的 config/pghero.yml开发调试时经常需要调整阈值、数据库数量或开关实验功能。仓库的配置生成器rails generate pghero:config实现见 lib/generators/pghero/config_generator.rb会生成config/pghero.yml模板全文见 lib/generators/pghero/templates/config.yml.tt。模板使用 ERB 语法%% ... %渲染为% ... %因此配置中可以内嵌环境变量引用。各配置项如下数据库定义databases: primary: # Database URL (defaults to app database) # url: % ENV[DATABASE_URL] % # System stats # aws_db_instance_identifier: my-instance # gcp_database_id: my-project:my-instance # Add more databases # other: # url: % ENV[OTHER_DATABASE_URL] %databases是 PgHero 4.x 以来的首选配置格式从 lib/pghero.rb 看若配置文件存在databases键则直接采用否则要求按 Rails 环境分节的旧格式否则报Invalid config file。每个数据库节点可以单独覆盖url、AWS/GCP 标识等。阈值与行为参数# Minimum time for long running queries # long_running_query_sec: 60 # Minimum average time for slow queries # slow_query_ms: 20 # Minimum calls for slow queries # slow_query_calls: 100 # Minimum connections for high connections warning # total_connections_threshold: 500 # Minimum size for unused indexes # unused_index_megabytes: 10这些阈值在 lib/pghero/database.rb 中都有对应的读取逻辑且遵循数据库级配置 全局配置 环境变量默认值的解析顺序。例如long_running_query_secconfig[long_running_query_sec] || PgHero.config[long_running_query_sec] || PgHero.long_running_query_sec默认 60 秒slow_query_ms默认 20 毫秒环境变量PGHERO_SLOW_QUERY_MSslow_query_calls默认 100 次环境变量PGHERO_SLOW_QUERY_CALLStotal_connections_threshold默认 500环境变量PGHERO_TOTAL_CONNECTIONS_THRESHOLDunused_index_megabytes默认 10 MB在 lib/pghero/database.rb 中换算为字节数。执行计划与可视化# Explain functionality # explain: true / false / analyze # Statement timeout for explain # explain_timeout_sec: 10 # Visualize URL for explain # visualize_url: https://...explain支持三个值true仅 EXPLAIN、false禁用、analyzeEXPLAIN ANALYZE。explain_enabled?判定逻辑见 lib/pghero.rbexplain_timeout_sec默认 10 秒visualize_url默认指向一个通用的执行计划可视化服务未配置时走PGHERO_VISUALIZE_URL环境变量。时区、认证与统计存储# Time zone (defaults to app time zone) # time_zone: Pacific Time (US Canada) # Basic authentication # username: admin # password: % ENV[PGHERO_PASSWORD] % # Stats database URL (defaults to app database) # stats_database_url: % ENV[PGHERO_STATS_DATABASE_URL] %time_zone在引擎初始化时被读入见 lib/pghero/engine.rbusername/password提供基本认证同时支持PGHERO_USERNAME/PGHERO_PASSWORD环境变量见 lib/pghero.rbstats_database_url允许把历史统计表放到独立的数据库默认与应用共用同一数据库见 lib/pghero.rb。云平台系统指标# AWS configuration (defaults to app AWS config) # aws_access_key_id: % ENV[AWS_ACCESS_KEY_ID] % # aws_secret_access_key: % ENV[AWS_SECRET_ACCESS_KEY] % # aws_region: us-east-1AWS 凭证、区域、aws_db_instance_identifier与gcp_database_id的完整解析逻辑位于 lib/pghero/database.rb覆盖了配置项、全局配置与PGHERO_*/AWS_*环境变量的多种组合。实验性开关# Disable killing queries and connections # disable_kill: true # Filter data from queries (experimental) # filter_data: truedisable_kill: true会隐藏仪表盘上的 kill 类按钮kill_enabled?逻辑见 lib/pghero.rbfilter_data是实验性功能开启时要求额外加载pg_queryGem否则在 lib/pghero/database.rb 的filter_data方法中直接抛出Error: pg_query required for filter_data。常用开发手段Rake 任务与测试统计采集与清理任务开发环境初始化后可以用仓库自带 Rake 任务定义于 lib/tasks/pghero.rake手动触发采集验证统计链路是否打通# 采集当前 pg_stat_statements 快照写入 pghero_query_stats bundle exec rake pghero:capture_query_stats # 采集空间快照写入 pghero_space_stats bundle exec rake pghero:capture_space_stats # 清理 14 天前的历史查询统计KEEP_DAYS 可调 bundle exec rake pghero:clean_query_stats KEEP_DAYS14 # 清理历史空间统计 bundle exec rake pghero:clean_space_stats KEEP_DAYS90对应的 Ruby 层入口是PgHero.capture_query_stats、PgHero.capture_space_stats、PgHero.clean_query_stats见 lib/pghero.rb。其中capture_query_stats的实际流程在 lib/pghero/methods/query_stats.rb先查询当前 Top 100 统计再调用pg_stat_statements_reset重置累计值最后把结果与时间戳一起insert_all写入历史表。这也是为什么官方建议该任务每 5 分钟调度一次——重置与采集成对出现保证时间窗口的连续性。生成器与配置的自动化测试仓库为生成器提供了专门的测试用例Rails Generators::TestCasetest/config_generator_test.rb断言生成器产出包含databases键的config/pghero.ymltest/query_stats_generator_test.rb断言产出db/migrate/create_pghero_query_stats.rb且包含create_table :pghero_query_statstest/space_stats_generator_test.rb断言产出db/migrate/create_pghero_space_stats.rb且包含create_table :pghero_space_stats。开发者在修改生成器模板或数据库结构时应同步运行这些测试如bundle exec rake test或按文件运行验证迁移文件的正确性。更进一步可选的贡献者配置挂载引擎与安全认证如果你希望把开发环境扩展成在自己的 Rails 应用中调试 PgHero核心两步是 Gemfile 添加gem pghero并在config/routes.rb中挂载引擎mount PgHero::Engine, at: pghero生产环境务必做好访问控制例如配置ENV[PGHERO_USERNAME]/ENV[PGHERO_PASSWORD]基本认证或用 Devise 的authenticate包裹挂载语句。这部分细节见 guides/Rails.md。建议索引功能要开发/调试 Suggested Indexes 相关功能需在 Gemfile 中加入gem pg_query, 6并确保历史查询统计已启用其原理与配置细节记录在 guides/Suggested-Indexes.md 中。权限模型PgHero 官方强烈建议为仪表盘创建一个专用、只读优先的数据库用户涉及的最小权限集可参考 guides/Permissions.md。这同样适用于开发库——避免使用超级用户跑开发环境可以减少误操作对本地数据的影响。常见问题排查要点foreman start后访问 5000 端口失败确认Procfile中定义的进程确实包含 web 进程且没有其他服务占用 5000可换PORT5100 foreman start验证。迁移失败提示表已存在开发库若被反复重建可先dropdb pghero_dev createdb pghero_dev再重跑bundle exec rails db:migrate。仪表盘 Queries 页无数据PgHero 的查询统计依赖 PostgreSQL 扩展pg_stat_statements。仪表盘首页通常可直接点击启用若要手动验证可在开发库中执行CREATE EXTENSION IF NOT EXISTS pg_stat_statements对应 lib/pghero/methods/query_stats.rb 的enable_query_stats。修改生成器模板不生效Generator 的模板文件位于 lib/generators/pghero/templates/改动后需重新执行rails generate pghero:query_stats/pghero:space_stats重新生成迁移并确保迁移版本号不冲突。小结从 guides/Contributing.md 出发本文把 PgHero 的本地开发环境搭建完整还原为克隆仓库 → 建库 → 生成统计表 → 迁移 → 启动仪表盘五个步骤并借助仓库源码逐层展开其背后机制Generator 如何生成统计表结构、pghero_queries/pghero_query_stats/pghero_space_stats三张表各自的字段设计与索引策略、config/pghero.yml中全部配置项的语义与解析优先级、以及 Rake 任务与生成器测试的用法。掌握这套流程后你就能在一个可运行、可观测的环境中修改 PgHero 的 SQL 采集逻辑、仪表盘视图、配置解析或生成器模板并通过仓库内置的测试用例验证改动从而以规范的姿态参与到这个开源项目中。赞分享数据库可观测性运维【免费下载链接】pgheroA performance dashboard for Postgres项目地址https://gitcode.com/gh_mirrors/pg/pghero点击查看免费下载相关推荐PgHero 实战指南用 Docker 与 Rails Engine 搭建 PostgreSQL 性能监控仪表盘PgHero 实战指南用 Docker 与 Rails Engine 搭建 PostgreSQL 性能监控仪表盘 PgHero 是一个面向 PostgreSQ数据库可观测性运维bolt.diy 贡献指南从本地开发环境搭建到 Docker 部署的完整参与手册bolt.diy 贡献指南从本地开发环境搭建到 Docker 部署的完整参与手册 本指南以 bolt.diy 仓库根目录的 CONTRIBUTING.md hAI 应用代码智能体AI Agent大模型开发工具mcp-use 云端部署实战将 OpenAPI 生成的 MCP Server 一键发布到 Manufact 云并接入 ChatGPT / Claudemcp use 云端部署实战将 OpenAPI 生成的 MCP Server 一键发布到 Manufact 云并接入 ChatGPT / Claude 本文以后端MCP 服务MCP ClientsAI Agent人工智能上一篇Anki 同步限制把「集合大小超出限制」调回可控范围下一篇Lightweight Charts与Three.js集成探索3D金融数据可视化终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
