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 的
postgresqlintegration 会自动跳过未启用该扩展的实例，日志只写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+）或SELECTonpg_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 默认连接
postgresDB，但如果业务库不在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 的
postgresqlintegration 如果遇到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 日志第三层嵌套里，不翻根本看不到。
