SQL Datadog / New Relic 的数据库监控集成与 query metrics 采集配置

pg_stat_statements 是 datadog 和 new relic 采集 postgresql 查询指标的前提，必须手动启用：修改 shared_preload_libraries、重启/重载、在目标库执行 create extension，并授予监控用户 pg_read_all_data 或 select 权限。

为什么 pg_stat_statements 是 Datadog / New Relic 采集 query metrics 的前提

没有启用 pg_stat_statements，Datadog 的 postgresql.queries.* 指标和 New Relic 的 databaseStatementSample 根本不会上报——不是配置漏了，是 PostgreSQL 压根没生成这些数据。

它不是默认开启的扩展，必须手动加载并重启或重载。很多团队在 Agent 配置里反复调 query_metrics: true 却看不到慢查询 TopN，卡在这一步。

• PostgreSQL 14+：确认 shared_preload_libraries 包含 'pg_stat_statements'（注意单引号和逗号）
• 修改 postgresql.conf 后必须 pg_ctl reload 或重启，CREATE EXTENSION 不够
• Datadog Agent 要求 pg_stat_statements 版本 ≥ 1.9（对应 PG 12+），旧版可能报 function "pg_stat_statements_reset()" does not exist
• New Relic 的 postgresql integration 会自动跳过未启用该扩展的实例，日志只写 Skipping database: no pg_stat_statements，不报错

Datadog Agent 中 pg_stat_statements 相关配置的关键字段

Datadog 的 postgresql.d/conf.yaml 里，query_metrics 开关只是表层，真正决定能否拿到 normalized query、latency 分布、calls 计数的是底层对 pg_stat_statements 的查询逻辑是否生效。

• query_metrics: true 必须配合 collect_activity_metrics: false（否则会因锁竞争导致 pg_stat_statements 查询超时）
• custom_queries 不能覆盖或干扰内置的 pg_stat_statements 查询；如果自定义了同名 query 字段，Agent 会静默丢弃内置指标
• max_query_length 默认 5000，但若应用大量使用 ORM 生成超长动态 SQL（如 django 的 IN 列表 > 1000 项），会被截断，导致相同逻辑的 query 被识别为不同语句——建议设为 10000 并观察 postgresql.queries.query_length_exceeded 指标
• Agent 日志中出现 Failed to run pg_stat_statements query: permission denied？说明监控用户缺少 pg_read_all_data 角色（PG 14+）或 SELECT on pg_stat_statements（旧版）

New Relic 的 postgresql integration 如何区分 slow vs. normal query metrics

New Relic 不像 Datadog 那样直接暴露 raw pg_stat_statements 数据，而是通过采样 + 聚合生成 DatabaseStatementSample 事件，slow query 的判定完全依赖 duration 阈值，且这个阈值不能在 ui 里改，只能在集成配置中硬编码。

• slow_query_threshold_ms 默认是 1000，但实际生效需满足两个条件：① query 在 pg_stat_statements 中的 total_time ≥ 该值；② 该 query 的 calls ≥ min_calls_to_collect（默认 10）
• 如果想捕获亚秒级抖动，比如 SELECT count(*) 偶发 300ms，需把 slow_query_threshold_ms 改成 300，同时把 min_calls_to_collect 降到 1，否则低频但高延迟的 query 会被过滤掉
• 注意：New Relic 会自动对 query text 做 normalization（参数替换为 $1、$2），但若应用用字符串拼接构造 SQL（如 "WHERE id = " + user_id），则无法归一化，每个 ID 都算独立 query，cardinality 爆炸，Dashboard 卡死
• 验证是否生效：查 NRQL FROM DatabaseStatementSample SELECT count(*) WHERE duration > 300，再对比 SELECT count(*) FROM pg_stat_statements WHERE total_time / calls > 300

跨 schema / extension 权限问题导致 query metrics 采集中断

当数据库启用了多 schema 或自定义 extension（如 timescaledb、citus），pg_stat_statements 的视图行为可能变化，Agent 查询失败却不报具体原因，只显示 Query execution failed。

• Datadog Agent 默认连接 postgres DB，但如果业务库不在 postgres，且 pg_stat_statements 未在目标 DB 中 CREATE EXTENSION，指标就为空——每个 DB 都要单独执行 CREATE EXTENSION if NOT EXISTS pg_stat_statements
• TimescaleDB 用户常见坑：pg_stat_statements 在 hypertable 上的 total_time 可能被低估，因为部分执行计划走的是 timescaledb 内部优化路径，不经过标准 planner hook；此时应优先看 timescaledb.background_workers 和 hypertable_chunk_stats
• New Relic 的 postgresql integration 如果遇到 relation "pg_stat_statements" does not exist，别急着重装 extension，先 c target_db 然后 SELECT * FROM pg_extension WHERE extname = 'pg_stat_statements'; —— 很可能是 extension 只装在 template1 或 postgres 库里

最常被忽略的一点：所有监控用户（datadog、newrelic）必须有 USAGE on public schema（或 extension 所在 schema），否则连 pg_stat_statements 这个名字都解析不了，错误信息藏在 Agent debug 日志第三层嵌套里，不翻根本看不到。