尧图网页设计 
Nightingale 集成 PostgreSQL 监控采集categraf 账号授权、配置详解与内置仪表盘告警实践【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingaleNightingale 通过其采集器 categraf 以普通 client 方式连接 PostgreSQL 实例并拉取监控指标。本指南以仓库中的 PostgreSQL 集成文档 为主体完整讲解从创建专用监控账号、配置postgresql.toml采集实例到引入内置仪表盘与告警规则的端到端落地过程读完即可在生产环境快速接入 PostgreSQL 监控并掌握自定义业务指标查询的扩展方法。前置准备创建专用监控账号categraf 作为独立 client 连接 PostgreSQL 采集指标出于安全与最小权限原则建议创建专用监控账号而不是直接使用超级用户。在 PostgreSQL 中执行如下 SQLCREATE USER categraf WITH PASSWORD password; GRANT pg_monitor TO categraf; ALTER USER categraf SET default_transaction_read_only on;三段语句各自承担明确的职责CREATE USER categraf WITH PASSWORD password创建名为categraf的数据库账号password替换为实际密码GRANT pg_monitor TO categrafpg_monitor是 PostgreSQL 内置的预定义角色授予后可以读取pg_stat_*等监控视图如pg_stat_activity、pg_stat_database、pg_stat_bgwriter这是指标采集所需的最小权限集ALTER USER categraf SET default_transaction_read_only on将该账号的默认事务设置为只读确保即使采集器后续执行了意外 SQL也不会对业务数据产生写操作属于纵深防御手段。注意pg_monitor只解决监控视图的读取问题。只有当你在[[instances.metrics]]中配置了自定义业务表查询时才需要额外为对应 schema/table 授予USAGE与SELECT权限否则不建议放开更多权限。配置文件示例与参数详解Nightingale 仓库中为 PostgreSQL 集成预置了采集配置模板 integrations/PostgreSQL/collect/postgresql/postgresql.toml将其内容或下方示例拷贝到 categraf 的采集配置目录后即可生效。完整示例# Read metrics from one or many postgresql servers # # collect interval # interval 15 [[instances]] ## specify address via a url matching: ## postgres://[pqgotest[:password]]localhost[/dbname]?sslmode[disable|verify-ca|verify-full] ## or a simple string: ## hostlocalhost userpqgotest password... sslmode... dbnameapp_production ## ## All connection parameters are optional. ## ## Without the dbname parameter, the driver will default to a database ## with the same name as the user. This dbname is just for instantiating a ## connection with the server and doesnt restrict the databases we are trying ## to grab metrics for. ## # address hostlocalhost userpostgres sslmodedisable ## A custom name for the database that will be used as the server tag in the ## measurement output. If not specified, a default one generated from ## the connection address is used. # outputaddress db01 ## connection configuration. ## maxlifetime - specify the maximum lifetime of a connection. ## default is forever (0s) # max_lifetime 0s ## A list of databases to explicitly ignore. If not specified, metrics for all ## databases are gathered. Do NOT use with the databases option. # ignored_databases [postgres, template0, template1] ## A list of databases to pull metrics about. If not specified, metrics for all ## databases are gathered. Do NOT use with the ignored_databases option. # databases [app_production, testing] ## Whether to use prepared statements when connecting to the database. ## This should be set to false when connecting through a PgBouncer instance ## with pool_mode set to transaction. #prepared_statements true模板顶部注释了采集周期选项interval 15单位秒取消注释即可调整拉取频率。下面逐一说明各参数参数作用默认行为 / 建议addressPostgreSQL 连接串支持 URL 与 keyvalue 两种写法见下节必填未指定dbname时驱动默认连接与用户名同名的数据库outputaddress作为输出指标中server标签的自定义名称不填时自动从连接地址生成max_lifetime连接的最大存活时长Gotime.Duration格式默认0s表示连接永不失效ignored_databases显式忽略的数据库列表不配置时采集全部数据库不可与databases同时使用databases显式指定要采集指标的数据库列表不配置时采集全部数据库不可与ignored_databases同时使用prepared_statements是否使用预编译语句连接数据库默认true经 PgBouncer 且pool_modetransaction时应设为false关于databases/ignored_databases的互斥关系模板注释中反复强调Do NOT use with两者只能二选一否则配置含义冲突会导致不可预期的采集范围。默认采集全部数据库时通常会配合ignored_databases排除系统库postgres、template0、template1以减少无效指标与标签基数。address 的两种连接写法address支持两种等价的连接串格式# 1) URL 形式 address postgres://pqgotest:passwordlocalhost/app_production?sslmodedisable # 2) keyvalue 形式 address host192.168.11.181 port5432 usercategraf passwordpassword sslmodedisableURL 形式的完整模板为postgres://[user[:password]]host[/dbname]?sslmode[disable|verify-ca|verify-full]keyvalue 形式支持host、port、user、password、sslmode、dbname等参数全部连接参数均为可选项。sslmode的取值对应 PostgreSQL 的标准安全等级disable不加密、verify-ca校验 CA、verify-full校验 CA 且校验主机名内网环境常用disable以降低开销公网或跨机房传输建议至少verify-ca。有一点容易误解连接串里的dbname只用于建立初始连接并不会限制采集的数据库范围。采集哪些库由databases/ignored_databases决定。自定义业务指标查询除了内置的pg_stat_*指标集成模板还支持通过[[instances.metrics]]自定义 SQL 查询将任意业务指标纳入采集。以统计各会话状态的连接数为例[[instances.metrics]] measurement sessions label_fields [ state ] metric_fields [ value ] timeout 3s request SELECT COALESCE(state, unknown) AS state, COUNT(*)::double precision AS value FROM pg_stat_activity GROUP BY COALESCE(state, unknown) 各字段含义measurement指标名即写入时序库的 measurement/指标前缀label_fieldsSQL 结果中作为标签label输出的列名此处state会成为指标标签metric_fieldsSQL 结果中作为指标值的列名此处value为数值timeout单次自定义查询的超时时间防止慢 SQL 阻塞采集request要执行的 SQL。注意示例中对state使用了COALESCE(..., unknown)兜底并把COUNT(*)显式::double precision转为浮点避免空值与整型除法影响指标质量。当自定义查询涉及业务表时才需要额外授予对应 schema/table 的USAGE与SELECT权限这与前文账号授权一节相呼应。采集指标的输出形态categraf 采集到的 PostgreSQL 指标以postgresql_前缀写入时序库且按数据库打上server、db标签。结合内置仪表盘 integrations/PostgreSQL/dashboards/postgresql_by_categraf.json 中的查询表达式可以还原出主要指标族主要包括两大类pg_stat_database 维度按数据库细分postgresql_numbackends当前连接数postgresql_blks_hit/postgresql_blks_read缓存命中/从磁盘读取的数据块数二者相除即缓存命中率postgresql_deadlocks死锁累计次数postgresql_conflicts与恢复冲突被取消的查询次数仅备库出现postgresql_xact_commit/postgresql_xact_rollback提交/回滚事务数postgresql_tup_returned/postgresql_tup_fetched/postgresql_tup_inserted/postgresql_tup_updated/postgresql_tup_deleted查询扫描行数、返回行数与增删改行数postgresql_temp_files/postgresql_temp_bytes临时文件数量与字节数postgresql_blk_read_time/postgresql_blk_write_time读写数据文件耗时需要track_io_timingon才有意义。pg_stat_bgwriter 维度实例级postgresql_checkpoints_timed/postgresql_checkpoints_req超时触发的检查点次数 / 因 WAL 达到max_wal_size或手动触发的检查点次数postgresql_checkpoint_write_time/postgresql_checkpoint_sync_time检查点写入 page cache 与 fsync 落盘耗时postgresql_buffers_checkpoint/postgresql_buffers_clean/postgresql_buffers_backend/postgresql_buffers_backend_fsynccheckpoint、bgwriter、backend 进程写入的数据块数及 backend 的 fsync 次数。仪表盘 JSON 中为每个面板都写了指标解读如returned 远大于 fetched代表查询效率低存在全表扫描应增加索引对应的多语言词条维护在 integrations/PostgreSQL/i18n/en_US.json可作为指标语义的权威参考。快速接入内置仪表盘与告警规则集成目录下预置了可直接导入使用的仪表盘与告警规则无需从零编写 PromQL仪表盘integrations/PostgreSQL/dashboards/postgresql_by_categraf.json名称为postgresql by categraf包含连接数、缓存命中率、死锁数、冲突数、事务统计、数据查询统计、数据更新统计、生成临时文件统计、数据库读写时间统计、checkpoint 分布、checkpoint 写文件时间分布、数据块写入分布等面板提供datasource、server、db三个模板变量导入后选择 Prometheus 数据源即可按实例和数据库筛选。告警规则integrations/PostgreSQL/alerts/postgresql_by_categraf.json内置 5 条基于 PromQL 的告警默认disabled1导入后需手动启用告警名称PromQL触发条件说明Postgresql downpostgresql_up!1实例不可达/进程异常posgresql读取时间过高rate(postgresql_blk_read_time[5m]) 100读盘耗时过高通常意味着内存不足postgresql写入时间过高rate(postgresql_blk_write_time[5m]) 100写盘耗时过高cache 偏小或 IO 尖峰postgresql有死锁increase(postgresql_deadlocks[10m]) 010 分钟内出现死锁Postgresql缓存命中率低于50%rate(postgresql_blks_hit[5m])*100/(rate(postgresql_blks_hit[5m])rate(postgresql_blks_read[5m])) 50缓存命中率跌破 50%这些规则的评价周期为 30sprom_eval_interval持续 60s 触发prom_for_duration并携带annotations.action处置建议。例如缓存命中率低于 50%的处置动作包括排除实例刚重启导致的缓存冷启动、用pg_stat_statements按shared_blks_read排序找出读盘最多的 SQL 补索引、将shared_buffers调至物理内存的 25% 左右、错峰执行大表全量扫描任务读/写时间过高则要求先确认SHOW track_io_timing为on否则指标恒为 0并配合iostat -x 1排查磁盘是否打满。这些处置建议同样在 i18n/en_US.json 中提供了英文对照可直接作为告警通知模板内容。集成机制的实现原理理解上述文件如何生效有助于排查配置了却没数据的问题。Nightingale 服务启动时由 center/integration/init.go 扫描integrations目录每个子目录作为一个组件component.Ident读取其icon目录作为 Logo、读取markdown/README.lang.md作为组件文档、读取dashboards、alerts目录下的 JSON 注册为内置仪表盘与告警规则i18n目录下的 JSON 则作为多语言词条表中文原文 英文翻译最终写入内置 payload 库供用户在页面上导入使用。这就是本文所讲 README、仪表盘、告警规则能直接出现在 Nightingale 平台集成中心的底层原因。另一方面采集到的postgresql_*指标进入时序库后在 Nightingale 中还可以通过内建的 PostgreSQL 数据源类型标识pgsql实现位于 datasource/postgresql/postgresql.go直接对 PostgreSQL 执行查询该插件支持ShowDatabases/ShowTables元数据浏览QueryData/QueryLog执行任意 SQL 并返回时序或日志结果查询支持$__时间宏替换如$__timeFilterSQL 中的库名会被自动规范化为dbname.schema.table形式以兼容 PostgreSQL 的大小写语义。注意这一数据源插件与本文的 categraf 采集链路是两个独立模块——前者面向用 PostgreSQL 存监控查询数据后者才是监控 PostgreSQL 本身两者可同时启用、互不冲突。总结接入 PostgreSQL 监控的完整链路为建账号pg_monitor 只读→ 配置采集address/databases/ignored_databases→ 可选自定义 SQL 指标 → 导入内置仪表盘与告警规则。仓库中的 README、采集模板、仪表盘 与 告警规则 构成了开箱即用的完整闭环用户只需按本文完成账号授权与配置替换即可获得覆盖连接数、事务、缓存、checkpoint、死锁等核心维度的 PostgreSQL 可观测能力。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nightingale 集成 PostgreSQL 监控采集：categraf 账号授权、配置详解与内置仪表盘告警实践
Nightingale 集成 PostgreSQL 监控采集categraf 账号授权、配置详解与内置仪表盘告警实践【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingaleNightingale 通过其采集器 categraf 以普通 client 方式连接 PostgreSQL 实例并拉取监控指标。本指南以仓库中的 PostgreSQL 集成文档 为主体完整讲解从创建专用监控账号、配置postgresql.toml采集实例到引入内置仪表盘与告警规则的端到端落地过程读完即可在生产环境快速接入 PostgreSQL 监控并掌握自定义业务指标查询的扩展方法。前置准备创建专用监控账号categraf 作为独立 client 连接 PostgreSQL 采集指标出于安全与最小权限原则建议创建专用监控账号而不是直接使用超级用户。在 PostgreSQL 中执行如下 SQLCREATE USER categraf WITH PASSWORD password; GRANT pg_monitor TO categraf; ALTER USER categraf SET default_transaction_read_only on;三段语句各自承担明确的职责CREATE USER categraf WITH PASSWORD password创建名为categraf的数据库账号password替换为实际密码GRANT pg_monitor TO categrafpg_monitor是 PostgreSQL 内置的预定义角色授予后可以读取pg_stat_*等监控视图如pg_stat_activity、pg_stat_database、pg_stat_bgwriter这是指标采集所需的最小权限集ALTER USER categraf SET default_transaction_read_only on将该账号的默认事务设置为只读确保即使采集器后续执行了意外 SQL也不会对业务数据产生写操作属于纵深防御手段。注意pg_monitor只解决监控视图的读取问题。只有当你在[[instances.metrics]]中配置了自定义业务表查询时才需要额外为对应 schema/table 授予USAGE与SELECT权限否则不建议放开更多权限。配置文件示例与参数详解Nightingale 仓库中为 PostgreSQL 集成预置了采集配置模板 integrations/PostgreSQL/collect/postgresql/postgresql.toml将其内容或下方示例拷贝到 categraf 的采集配置目录后即可生效。完整示例# Read metrics from one or many postgresql servers # # collect interval # interval 15 [[instances]] ## specify address via a url matching: ## postgres://[pqgotest[:password]]localhost[/dbname]?sslmode[disable|verify-ca|verify-full] ## or a simple string: ## hostlocalhost userpqgotest password... sslmode... dbnameapp_production ## ## All connection parameters are optional. ## ## Without the dbname parameter, the driver will default to a database ## with the same name as the user. This dbname is just for instantiating a ## connection with the server and doesnt restrict the databases we are trying ## to grab metrics for. ## # address hostlocalhost userpostgres sslmodedisable ## A custom name for the database that will be used as the server tag in the ## measurement output. If not specified, a default one generated from ## the connection address is used. # outputaddress db01 ## connection configuration. ## maxlifetime - specify the maximum lifetime of a connection. ## default is forever (0s) # max_lifetime 0s ## A list of databases to explicitly ignore. If not specified, metrics for all ## databases are gathered. Do NOT use with the databases option. # ignored_databases [postgres, template0, template1] ## A list of databases to pull metrics about. If not specified, metrics for all ## databases are gathered. Do NOT use with the ignored_databases option. # databases [app_production, testing] ## Whether to use prepared statements when connecting to the database. ## This should be set to false when connecting through a PgBouncer instance ## with pool_mode set to transaction. #prepared_statements true模板顶部注释了采集周期选项interval 15单位秒取消注释即可调整拉取频率。下面逐一说明各参数参数作用默认行为 / 建议addressPostgreSQL 连接串支持 URL 与 keyvalue 两种写法见下节必填未指定dbname时驱动默认连接与用户名同名的数据库outputaddress作为输出指标中server标签的自定义名称不填时自动从连接地址生成max_lifetime连接的最大存活时长Gotime.Duration格式默认0s表示连接永不失效ignored_databases显式忽略的数据库列表不配置时采集全部数据库不可与databases同时使用databases显式指定要采集指标的数据库列表不配置时采集全部数据库不可与ignored_databases同时使用prepared_statements是否使用预编译语句连接数据库默认true经 PgBouncer 且pool_modetransaction时应设为false关于databases/ignored_databases的互斥关系模板注释中反复强调Do NOT use with两者只能二选一否则配置含义冲突会导致不可预期的采集范围。默认采集全部数据库时通常会配合ignored_databases排除系统库postgres、template0、template1以减少无效指标与标签基数。address 的两种连接写法address支持两种等价的连接串格式# 1) URL 形式 address postgres://pqgotest:passwordlocalhost/app_production?sslmodedisable # 2) keyvalue 形式 address host192.168.11.181 port5432 usercategraf passwordpassword sslmodedisableURL 形式的完整模板为postgres://[user[:password]]host[/dbname]?sslmode[disable|verify-ca|verify-full]keyvalue 形式支持host、port、user、password、sslmode、dbname等参数全部连接参数均为可选项。sslmode的取值对应 PostgreSQL 的标准安全等级disable不加密、verify-ca校验 CA、verify-full校验 CA 且校验主机名内网环境常用disable以降低开销公网或跨机房传输建议至少verify-ca。有一点容易误解连接串里的dbname只用于建立初始连接并不会限制采集的数据库范围。采集哪些库由databases/ignored_databases决定。自定义业务指标查询除了内置的pg_stat_*指标集成模板还支持通过[[instances.metrics]]自定义 SQL 查询将任意业务指标纳入采集。以统计各会话状态的连接数为例[[instances.metrics]] measurement sessions label_fields [ state ] metric_fields [ value ] timeout 3s request SELECT COALESCE(state, unknown) AS state, COUNT(*)::double precision AS value FROM pg_stat_activity GROUP BY COALESCE(state, unknown) 各字段含义measurement指标名即写入时序库的 measurement/指标前缀label_fieldsSQL 结果中作为标签label输出的列名此处state会成为指标标签metric_fieldsSQL 结果中作为指标值的列名此处value为数值timeout单次自定义查询的超时时间防止慢 SQL 阻塞采集request要执行的 SQL。注意示例中对state使用了COALESCE(..., unknown)兜底并把COUNT(*)显式::double precision转为浮点避免空值与整型除法影响指标质量。当自定义查询涉及业务表时才需要额外授予对应 schema/table 的USAGE与SELECT权限这与前文账号授权一节相呼应。采集指标的输出形态categraf 采集到的 PostgreSQL 指标以postgresql_前缀写入时序库且按数据库打上server、db标签。结合内置仪表盘 integrations/PostgreSQL/dashboards/postgresql_by_categraf.json 中的查询表达式可以还原出主要指标族主要包括两大类pg_stat_database 维度按数据库细分postgresql_numbackends当前连接数postgresql_blks_hit/postgresql_blks_read缓存命中/从磁盘读取的数据块数二者相除即缓存命中率postgresql_deadlocks死锁累计次数postgresql_conflicts与恢复冲突被取消的查询次数仅备库出现postgresql_xact_commit/postgresql_xact_rollback提交/回滚事务数postgresql_tup_returned/postgresql_tup_fetched/postgresql_tup_inserted/postgresql_tup_updated/postgresql_tup_deleted查询扫描行数、返回行数与增删改行数postgresql_temp_files/postgresql_temp_bytes临时文件数量与字节数postgresql_blk_read_time/postgresql_blk_write_time读写数据文件耗时需要track_io_timingon才有意义。pg_stat_bgwriter 维度实例级postgresql_checkpoints_timed/postgresql_checkpoints_req超时触发的检查点次数 / 因 WAL 达到max_wal_size或手动触发的检查点次数postgresql_checkpoint_write_time/postgresql_checkpoint_sync_time检查点写入 page cache 与 fsync 落盘耗时postgresql_buffers_checkpoint/postgresql_buffers_clean/postgresql_buffers_backend/postgresql_buffers_backend_fsynccheckpoint、bgwriter、backend 进程写入的数据块数及 backend 的 fsync 次数。仪表盘 JSON 中为每个面板都写了指标解读如returned 远大于 fetched代表查询效率低存在全表扫描应增加索引对应的多语言词条维护在 integrations/PostgreSQL/i18n/en_US.json可作为指标语义的权威参考。快速接入内置仪表盘与告警规则集成目录下预置了可直接导入使用的仪表盘与告警规则无需从零编写 PromQL仪表盘integrations/PostgreSQL/dashboards/postgresql_by_categraf.json名称为postgresql by categraf包含连接数、缓存命中率、死锁数、冲突数、事务统计、数据查询统计、数据更新统计、生成临时文件统计、数据库读写时间统计、checkpoint 分布、checkpoint 写文件时间分布、数据块写入分布等面板提供datasource、server、db三个模板变量导入后选择 Prometheus 数据源即可按实例和数据库筛选。告警规则integrations/PostgreSQL/alerts/postgresql_by_categraf.json内置 5 条基于 PromQL 的告警默认disabled1导入后需手动启用告警名称PromQL触发条件说明Postgresql downpostgresql_up!1实例不可达/进程异常posgresql读取时间过高rate(postgresql_blk_read_time[5m]) 100读盘耗时过高通常意味着内存不足postgresql写入时间过高rate(postgresql_blk_write_time[5m]) 100写盘耗时过高cache 偏小或 IO 尖峰postgresql有死锁increase(postgresql_deadlocks[10m]) 010 分钟内出现死锁Postgresql缓存命中率低于50%rate(postgresql_blks_hit[5m])*100/(rate(postgresql_blks_hit[5m])rate(postgresql_blks_read[5m])) 50缓存命中率跌破 50%这些规则的评价周期为 30sprom_eval_interval持续 60s 触发prom_for_duration并携带annotations.action处置建议。例如缓存命中率低于 50%的处置动作包括排除实例刚重启导致的缓存冷启动、用pg_stat_statements按shared_blks_read排序找出读盘最多的 SQL 补索引、将shared_buffers调至物理内存的 25% 左右、错峰执行大表全量扫描任务读/写时间过高则要求先确认SHOW track_io_timing为on否则指标恒为 0并配合iostat -x 1排查磁盘是否打满。这些处置建议同样在 i18n/en_US.json 中提供了英文对照可直接作为告警通知模板内容。集成机制的实现原理理解上述文件如何生效有助于排查配置了却没数据的问题。Nightingale 服务启动时由 center/integration/init.go 扫描integrations目录每个子目录作为一个组件component.Ident读取其icon目录作为 Logo、读取markdown/README.lang.md作为组件文档、读取dashboards、alerts目录下的 JSON 注册为内置仪表盘与告警规则i18n目录下的 JSON 则作为多语言词条表中文原文 英文翻译最终写入内置 payload 库供用户在页面上导入使用。这就是本文所讲 README、仪表盘、告警规则能直接出现在 Nightingale 平台集成中心的底层原因。另一方面采集到的postgresql_*指标进入时序库后在 Nightingale 中还可以通过内建的 PostgreSQL 数据源类型标识pgsql实现位于 datasource/postgresql/postgresql.go直接对 PostgreSQL 执行查询该插件支持ShowDatabases/ShowTables元数据浏览QueryData/QueryLog执行任意 SQL 并返回时序或日志结果查询支持$__时间宏替换如$__timeFilterSQL 中的库名会被自动规范化为dbname.schema.table形式以兼容 PostgreSQL 的大小写语义。注意这一数据源插件与本文的 categraf 采集链路是两个独立模块——前者面向用 PostgreSQL 存监控查询数据后者才是监控 PostgreSQL 本身两者可同时启用、互不冲突。总结接入 PostgreSQL 监控的完整链路为建账号pg_monitor 只读→ 配置采集address/databases/ignored_databases→ 可选自定义 SQL 指标 → 导入内置仪表盘与告警规则。仓库中的 README、采集模板、仪表盘 与 告警规则 构成了开箱即用的完整闭环用户只需按本文完成账号授权与配置替换即可获得覆盖连接数、事务、缓存、checkpoint、死锁等核心维度的 PostgreSQL 可观测能力。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考