实测AI智能降重工具效果！哪个工具网站更好用性价比更高？
2026/9/13 22:54:35
Vector 的 PostgreSQL Metrics 数据源深度解析：配置、指标字典与源码实现
【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector
导读
本文以 Vector 官方文档postgresql_metrics数据源（source）为线索，完整梳理该组件的定位、工作原理、全部配置参数与权限要求，并基于当前仓库的 CUE 元数据与 Rust 源码，逐条解读其输出的指标语义与实现细节。读者学完后将能独立配置 Vector 对 PostgreSQL 实例进行周期性指标采集，理解include_databases/exclude_databases的正则过滤机制、TLS 连接方式、版本兼容边界，以及每个指标的来源视图与单位换算规则。
说明：本文所依据的官方文档页面 postgresql_metrics.md 本身是一个由模板自动生成的占位文件，其真实内容由 postgresql_metrics.cue（组件元数据）与 generated/postgresql_metrics.cue（配置定义）两份 CUE 数据生成，下文内容均以这两份数据与 源码实现 为准。
组件定位与基本特性
postgresql_metrics是 Vector 内置的指标类数据源（component_kind: source），用于从 PostgreSQL 数据库周期性地采集统计信息并转换为 Vector 的 metric 事件流。其元数据定义位于 postgresql_metrics.cue，关键特性如下：
| 特性维度 | 取值 | 说明 |
|---|---|---|
| delivery | at_least_once | 至少一次投递语义（但该组件本身can_acknowledge返回false，不支持端到端确认） |
| deployment_roles | daemon、sidecar | 可作为守护进程或边车（sidecar）部署 |
| development | stable | 稳定级组件 |
| egress_method | batch | 批量输出 |
| stateful | false | 无状态组件，不支持检查点 |
| collect.checkpoint | disabled | 不启用检查点机制 |
| collect.from.service.versions | 9.6-13 | 官方声明支持的 PostgreSQL 版本范围为 9.6 ~ 13 |
| collect.from.interface.socket | outgoing / tcp + unix / ssl optional | 通过 TCP 或 Unix Socket 主动外连，TLS 可选 |
采集协议上，该组件通过 PostgreSQL 原生前端/后端协议（tokio-postgres）以出站（outgoing）方式连接数据库，支持 TCP 与 Unix Socket 两种传输，SSL 为可选（与sslmode参数联动）。从源码看，PostgresqlMetrics::new会解析 endpoint 并取出唯一主机（Host::Tcp或Host::Unix），若 URI 中包含多个 host 则直接报错MultipleHostsNotSupported，因此每个 endpoint 只能指向单一实例（src/sources/postgresql_metrics.rs）。
工作原理与数据来源
按 CUE 文档 的how_it_works说明，该组件通过向配置的 PostgreSQL 服务器发起 SQL 查询来收集指标。核心工作流程在 build 方法 中体现：
- 启动时为每个 endpoint 建立连接并校验版本；
- 以
scrape_interval_secs为周期驱动tokio::time::interval定时器； - 每个周期内使用
join_all并发地对所有 endpoint 执行collect，结果合并成一个 metric 批次； - 通过
send_batch一次性投递给下游 sink。
单次collect_metrics会并发执行三组查询（collect_metrics）：
| 查询来源视图 | 用途 | 说明 |
|---|---|---|
pg_stat_database | 数据库级统计 | 每个数据库一行，输出 20 个左右指标 |
pg_stat_database_conflicts | 恢复冲突统计 | 每个数据库一行，输出 5 个冲突计数器 |
pg_stat_bgwriter | 后台写进程统计 | 全局一行，输出 11 个指标 |
每次采集结束后，如果任一查询失败，该 endpoint 会输出up = 0的指标并记录内部错误事件，而不是中断整个管道；全部成功则输出up = 1并继续输出其余指标（collect）。
配置指南
postgresql_metrics的配置项定义于 generated/postgresql_metrics.cue，同时在 PostgresqlMetricsConfig 中由configurable_component宏生成。所有配置项如下：
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
endpoints | array<string> | 是 | — | 要抓取的 PostgreSQL 实例列表，每个元素必须是 libpq 连接 URI 格式 |
scrape_interval_secs | uint | 否 | 15 | 两次抓取之间的间隔，单位秒 |
namespace | string | 否 | postgresql | 覆盖该 source 输出指标的默认命名空间 |
include_databases | array<string> | 否 | — | 用 POSIX 正则匹配datname列，只采集匹配数据库的指标；不设置则采集所有数据库 |
exclude_databases | array<string> | 否 | — | 用 POSIX 正则匹配datname列，跳过匹配数据库的指标 |
tls | object | 否 | — | 连接 PostgreSQL 时的 TLS 配置 |
tls.ca_file | string | 是（配置 tls 时） | — | 附加 CA 证书文件的绝对路径，证书须为 DER 或 PEM（X.509）格式 |
一个最小可运行的配置示例：
sources: postgresql_metrics: type: postgresql_metrics endpoints: - postgresql://postgres:vector@localhost:5432/postgres scrape_interval_secs: 15完整配置示例（含数据库过滤与 TLS）
sources: postgresql_metrics: type: postgresql_metrics endpoints: - postgresql://postgres:vector@localhost:5432/postgres - postgresql:///postgres?host=/var/run/postgresql&user=vector&password=vector scrape_interval_secs: 30 namespace: postgresql include_databases: - "^postgres$" - "^vector$" - "^foo" exclude_databases: - "^template.*" tls: ca_file: certs/ca.pem要点说明：
endpoints支持 TCP（postgresql://user:pass@host:port/dbname）与 Unix Socket（postgresql:///dbname?host=/path/to/socket）两种形式；include_databases与exclude_databases可同时使用：先按 include 过滤出候选库，再用 exclude 剔除（见下文源码分析）；- 在
include_databases/exclude_databases列表中指定空字符串""可匹配datname为NULL的行（即共享对象相关的统计行）； - 配置
tls时可通过 URI 中的sslmode=require等参数指定加密策略，ca_file用于校验证书链。
将指标接入下游
sinks: prometheus: type: prometheus_exporter inputs: [postgresql_metrics] address: "0.0.0.0:9598" default_namespace: postgresql数据库账号权限要求
按 CUE 文档的 Required Privileges 一节，采集账号必须被允许对以下视图执行 SELECT 查询：
pg_stat_databasepg_stat_database_conflictspg_stat_bgwriter
实际部署中，可以创建一个只读监控账号并授予相应权限，例如：
CREATE USER vector_monitor WITH PASSWORD 'vector'; GRANT CONNECT ON DATABASE postgres TO vector_monitor; GRANT pg_monitor TO vector_monitor; -- PostgreSQL 10+ 推荐，涵盖统计视图只读访问（pg_monitor内置角色的引入属于 PostgreSQL 自身能力，若使用 9.6 等旧版本需改用对上述三个视图的显式 GRANT。）
输出指标字典
所有指标默认命名空间均为postgresql，均带endpoint（如postgresql:///postgres?host=localhost&port=5432）与host两个必选标签；凡来源于pg_stat_database/pg_stat_database_conflicts的指标额外带db（数据库名）标签。全部指标定义位于 CUE 元数据的 output.metrics 部分。
存活探针
| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
up | gauge | endpoint, host | PostgreSQL 服务器是否在线：采集成功为 1，失败为 0 |
pg_stat_database系列（带db标签）
| 指标 | 类型 | 说明 |
|---|---|---|
pg_stat_database_datid | gauge | 该数据库的 OID；共享对象行为 0 |
pg_stat_database_numbackends | gauge | 当前连接到该数据库的后端进程数（唯一反映当前状态的列，其余均为自上次重置以来的累计值） |
pg_stat_database_xact_commit_total | counter | 已提交事务数 |
pg_stat_database_xact_rollback_total | counter | 已回滚事务数 |
pg_stat_database_blks_read_total | counter | 磁盘块读取次数 |
pg_stat_database_blks_hit_total | counter | 缓冲区缓存命中次数（仅统计 PostgreSQL 缓冲池命中，不含操作系统文件系统缓存） |
pg_stat_database_tup_returned_total | counter | 查询返回的行数 |
pg_stat_database_tup_fetched_total | counter | 查询取回的行数 |
pg_stat_database_tup_inserted_total | counter | 插入行数 |
pg_stat_database_tup_updated_total | counter | 更新行数 |
pg_stat_database_tup_deleted_total | counter | 删除行数 |
pg_stat_database_conflicts_total | counter | 因恢复冲突被取消的查询数（仅备库出现） |
pg_stat_database_temp_files_total | counter | 临时文件创建数（无论成因是排序/哈希，也不受log_temp_files影响） |
pg_stat_database_temp_bytes_total | counter | 写入临时文件的总字节数 |
pg_stat_database_deadlocks_total | counter | 检测到的死锁数 |
pg_stat_database_checksum_failures_total | counter | 数据页校验和失败次数；未启用数据校验和时为 0（PostgreSQL 12+ 才输出） |
pg_stat_database_checksum_last_failure | gauge | 最近一次校验和失败的时间戳；未启用时为 0（PostgreSQL 12+ 才输出） |
pg_stat_database_blk_read_time_seconds_total | counter | 后端读取数据文件块耗时（毫秒，单位换算为秒）；未开启track_io_timing时为 0 |
pg_stat_database_blk_write_time_seconds_total | counter | 后端写入数据文件块耗时（毫秒，单位换算为秒）；未开启track_io_timing时为 0 |
pg_stat_database_stats_reset | gauge | 这些统计信息最近一次被重置的时间 |
pg_stat_database_conflicts系列（带db标签）
| 指标 | 类型 | 说明 |
|---|---|---|
pg_stat_database_conflicts_confl_tablespace_total | counter | 因表空间被删除而取消的查询数 |
pg_stat_database_conflicts_confl_lock_total | counter | 因锁超时被取消的查询数 |
pg_stat_database_conflicts_confl_snapshot_total | counter | 因快照过旧被取消的查询数 |
pg_stat_database_conflicts_confl_bufferpin_total | counter | 因缓冲页被钉住被取消的查询数 |
pg_stat_database_conflicts_confl_deadlock_total | counter | 因死锁被取消的查询数 |
pg_stat_bgwriter系列（无db标签）
| 指标 | 类型 | 说明 |
|---|---|---|
pg_stat_bgwriter_checkpoints_timed_total | counter | 定时触发的检查点次数 |
pg_stat_bgwriter_checkpoints_req_total | counter | 请求触发的检查点次数 |
pg_stat_bgwriter_checkpoint_write_time_seconds_total | counter | 检查点处理中写文件到磁盘的总耗时（毫秒换算为秒） |
pg_stat_bgwriter_checkpoint_sync_time_seconds_total | counter | 检查点处理中同步文件到磁盘的总耗时（毫秒换算为秒） |
pg_stat_bgwriter_buffers_checkpoint_total | counter | 检查点期间写入的缓冲页数 |
pg_stat_bgwriter_buffers_clean_total | counter | 后台写进程写入的缓冲页数 |
pg_stat_bgwriter_maxwritten_clean_total | counter | 后台写进程因写入过多缓冲页而停止清理扫描的次数 |
pg_stat_bgwriter_buffers_backend_total | counter | 后端直接写入的缓冲页数 |
pg_stat_bgwriter_buffers_backend_fsync_total | counter | 后端自行执行 fsync 的次数（正常由后台写进程处理） |
pg_stat_bgwriter_buffers_alloc_total | counter | 已分配的缓冲页数 |
pg_stat_bgwriter_stats_reset | gauge | 这些统计信息最近一次被重置的时间 |
源码级实现细节
版本检测与兼容边界
连接建立后，客户端会执行SHOW server_version_num并将结果解析为整数，若小于90600（即 PostgreSQL 9.6）则返回InvalidVersion错误并拒绝采集（build_client）。这与 CUE 中声明的versions: "9.6-13"一致。此外，checksum_failures与checksum_last_failure两个指标仅在client_version >= 120000（PostgreSQL 12+）时才被采集，因为pg_stat_database视图的这两列是 PG 12 新增的（collect_pg_stat_database）。
include_databases/exclude_databases的动态 SQL
DatnameFilter（src/sources/postgresql_metrics.rs）负责把正则列表编译成针对pg_stat_database与pg_stat_database_conflicts的WHERE子句：
- 每个 include 模式生成
datname ~ $n（POSIX 正则匹配），用OR连接后整体括号包裹； - 每个 exclude 模式生成
NOT (datname ~ $n ...)； - include 与 exclude 之间用
AND组合，先 include 后 exclude； - 列表中的
""会被单独提取：include 含""时追加datname IS NULL（用OR合并），exclude 含""时追加datname IS NOT NULL（用AND合并，且优先级高于 include）。
所有模式均通过参数化查询（$1、$2…）传入，避免 SQL 注入。集成测试test_host_include_databases_and_exclude_databases验证了include: ["template\\d+"]+exclude: ["template0"]最终只会留下template1的结果（src/sources/postgresql_metrics.rs）。
单位换算与端点脱敏
blk_read_time、blk_write_time、checkpoint_write_time、checkpoint_sync_time在 PostgreSQL 中单位是毫秒，源码统一除以 1000转换为秒后输出（如 collect_pg_stat_database）；endpoint标签并非原始 URI，而是经过config_to_endpoint重写、剔除用户名/密码等敏感信息后的脱敏连接串（如postgresql:///postgres?host=localhost&port=5432），同时仅保留非默认参数（如sslmode=require、target_session_attrs=read-write等），默认值会被省略（config_to_endpoint）。
错误处理与内部可观测性
采集失败时通过 PostgresqlMetricsCollectError 发出PostgreSQL query error.内部事件（stage=receiving，error_type=request_failed）并累加component_errors_total计数器；成功路径则分别发出EndpointBytesReceived、EventsReceived与CollectionCompleted事件，用于观测抓取字节数、事件量与耗时。组件自身的遥测指标为collect_completed_total与collect_duration_seconds（见 CUE telemetry 定义）。若下游send_batch返回错误（管道关闭），会发出StreamClosedError并终止采集循环。
测试验证
除单元测试generate_config外，源码底部包含一组需要postgresql_metrics-integration-testsfeature 启用的集成测试（src/sources/postgresql_metrics.rs），覆盖了本文提到的核心行为：
test_host：TCP 连接 + 完整指标采集，断言up == 1、命名空间为postgresql、存在endpoint/host标签，且三类查询均有代表性指标输出；test_local：Unix Socket 连接（postgresql:///postgres?host=...&user=vector&password=vector）；test_host_ssl：sslmode=require+ca_file的 TLS 连接；test_host_include_databases/test_host_exclude_databases/test_host_exclude_databases_empty/test_host_include_databases_and_exclude_databases：验证正则过滤与空串匹配 NULL 的行为。
这些测试依赖 test_util 中的 postgres 辅助函数（pg_url、pg_socket）提供测试库连接信息。
总结与最佳实践
postgresql_metrics组件以轻量的 SQL 抓取方式，将 PostgreSQL 的pg_stat_database、pg_stat_database_conflicts、pg_stat_bgwriter三大统计视图转化为带统一endpoint/host/db标签的指标流。实战中建议：
- 限定权限：为监控账号只授予对上述三个视图的 SELECT（或直接授予
pg_monitor）； - 善用数据库过滤：用
include_databases/exclude_databases精确控制采集范围，避免template库等无关库产生噪声； - 关注版本差异：9.6 以下不支持，12 以下无 checksum 相关指标；若需要 I/O 耗时指标，需在 PostgreSQL 侧开启
track_io_timing； - 配置告警：以
up == 0作为连接失败的即时信号，配合pg_stat_replication等指标（如需要可另行采集）完善数据库可观测体系。
更完整的组件文档页面可在 postgresql_metrics.md 模板 与其生成源 postgresql_metrics.cue 中查阅。
【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考