Grafana 监控面板

两套精选的 Grafana 监控面板，用于监控 Alauda CloudNativePG (CNPG) 集群，基于 CNPG 内置指标导出器构建：

static/grafana/cluster-overview.json — 集群健康状况：实例状态、主实例标识、复制堆积量、连接数、每秒事务数、缓存命中率、存储和 WAL 使用情况（24 个图表）。
static/grafana/backup-monitoring.json — 持续备份健康状况：距离上次成功备份的时间、备份失败指示、时间点恢复窗口、WAL 归档速率和积压量、WAL 容量（15 个图表）。

这两个监控面板都已在 Alauda Container Platform 上一个包含 2 个实例的 CNPG 集群中完成验证（通过 barman-cloud 插件将备份写入对象存储，使用 pgbench 负载）：每个图表查询都已验证可从平台 Prometheus 返回数据。

内置导出器与 `postgres-exporter` 对比

如果你来自基于 Zalando 的 PostgreSQL 技术栈，监控通常会使用一个单独的 postgres-exporter sidecar。CNPG 会在每个实例 Pod 中嵌入一个导出器（端口 9187）——无需额外部署：

	CNPG 内置导出器	`postgres-exporter`（Zalando 技术栈）
Deployment	位于每个实例 Pod 内，端口 `9187`	每个 cluster 额外一个 sidecar/Deployment
Connection	Pod 本地 socket，专用 `cnpg_metrics_exporter` role，无需密码 secret	通过环境变量使用 TCP DSN（需要管理 secret）
Metric prefix	`cnpg_`	`pg_`
Operator awareness	fencing、同步 Replica 数量、已使用节点、WAL 归档状态、备份时间戳	仅数据库级别
Custom queries	每个 cluster 的 `spec.monitoring.customQueriesConfigMap`	导出器全局 `queries.yaml`

不要将 postgres-exporter 挂接到 CNPG cluster 上——这样会重复抓取，而且仍然缺少 operator 级别的健康指标。如果你依赖 pg_stat_user_tables / pg_stat_statements 图表，请将这些查询迁移到 customQueriesConfigMap 中（查询 YAML 方言基本相同）；将监控面板序列从 pg_* 重命名为 cnpg_pg_*。

导出器暴露的内容

原生指标（cnpg_collector_*）：实例 up、PostgreSQL 版本、fencing、manual-switchover-required、已使用节点、同步 Replica 数量、WAL 段数量/大小、WAL 归档状态（ready/done），以及（PG ≥ 14）WAL 写入/同步统计。
默认查询（cnpg_<query>_*，来自 operator 管理的 cnpg-default-monitoring ConfigMap）：backends、pg_database、 pg_replication、pg_replication_slots、pg_stat_archiver、 pg_stat_bgwriter/pg_stat_checkpointer、pg_stat_database、 pg_stat_replication、pg_settings、pg_extensions。
插件指标：CNPG-i 插件通过同一端点发布指标。 barman-cloud 插件（此产品随附的备份方式）暴露 barman_cloud_cloudnative_pg_io_last_available_backup_timestamp、 ..._last_failed_backup_timestamp 和 ..._first_recoverability_point。

WARNING

使用由插件管理的备份时，旧版 cnpg_collector_last_available_backup_timestamp / ..._first_recoverability_point 指标会保持为 0——它们读取的是插件未设置的内置状态字段。备份监控面板会优先查询插件序列，并在没有数据时回退到内置序列，因此无论是插件、volume-snapshot，还是旧版内置 barman 备份都能正常工作。

安装

1. 创建带有平台要求标签的 PodMonitor

导出器始终可用；你需要添加的是一个 PodMonitor，以便平台 Prometheus 抓取它。在 Alauda Container Platform 中，平台 Prometheus （cpaas-system 中的 kube-prometheus-0）会选择 所有命名空间中的监控，但仅限于带有标签 prometheus: kube-prometheus 的对象：

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: <cluster-name>
  namespace: <cluster-namespace>
  labels:
    prometheus: kube-prometheus        # REQUIRED on ACP
spec:
  selector:
    matchLabels:
      cnpg.io/cluster: <cluster-name>
  podMetricsEndpoints:
    - port: metrics

TIP

在 Cluster 上设置 spec.monitoring.enablePodMonitor: true 也可以，但在 CNPG 1.29 中已弃用，并且生成的 PodMonitor 不带所需标签——如果你使用它，请通过 spec.inheritedMetadata.labels 传递该标签。

验证抓取结果：

kubectl -n cpaas-system port-forward svc/kube-prometheus-0-web 9090 &
curl -s 'http://127.0.0.1:9090/api/v1/query?query=cnpg_collector_up' | jq .data.result

2. 将 Grafana 指向平台 Prometheus

Grafana ≥ 9.x，使用 Prometheus 数据源。

WARNING

ACP Prometheus 服务（kube-prometheus-0-web.cpaas-system.svc:9090 和 Thanos query service）位于 OAuth（dex）代理之后——使用普通 URL 的数据源收到的是重定向，而不是数据。你可以为数据源配置一个 Authorization: Bearer <platform id_token> 自定义 HTTP header，或者如果 Grafana 运行在 cluster 内，则直接指向 Prometheus 容器端口（prometheus-kube-prometheus-0-0 Pod 上的 9090 端口不会被代理；OAuth sidecar 只负责服务的 target port）。

3. 导入监控面板

UI：Dashboards → New → Import → Upload JSON file — 下载 cluster-overview.json 和 backup-monitoring.json，在提示时选择你的 Prometheus 数据源。这两个监控面板都提供 namespace 和 cluster 模板变量（从 cnpg_collector_up 中发现），因此一次导入即可覆盖平台上的所有 CNPG cluster。

图表到指标映射

需求	图表（监控面板）	对应序列
实例在线/离线	Instances up（overview）	`cnpg_collector_up`
哪个 Pod 是主实例	Primary instance（overview）	`cnpg_pg_replication_in_recovery == 0`
复制堆积量	Replication lag（overview）	`cnpg_pg_replication_lag`、`cnpg_pg_stat_replication_*_lag_seconds`
连接数	Backends by state、Connection usage（overview）	`cnpg_backends_total`、`cnpg_pg_settings_setting`
每秒事务数	Transactions per second（overview）	`rate(cnpg_pg_stat_database_xact_commit[5m])`
缓存命中率	Cache hit ratio（overview）	`cnpg_pg_stat_database_blks_hit` 与 `blks_read`
上次备份 / 失败	Time since last successful backup（backup）	`barman_cloud_cloudnative_pg_io_last_available_backup_timestamp`（插件）以及 `cnpg_collector_*` 回退
PITR 窗口	Recovery window（backup）	`barman_cloud_cloudnative_pg_io_first_recoverability_point`（插件）以及回退
WAL 归档健康状态	WAL segments awaiting archive、WAL archive rate（backup）	`cnpg_collector_pg_wal_archive_status`、`cnpg_pg_stat_archiver_*`

备份大小是刻意未包含的：CNPG 不会将其作为指标导出。请从 Backup 资源状态（kubectl get backup <name> -o jsonpath='{.status}'）或对象存储中读取；Database size / WAL on disk 图表可作为容量替代指标。

已知限制

基于 pg_stat_replication 的图表只有在 primary 上且至少存在一个流复制 Replica 时才会产生数据——在 1 实例 cluster 上它们为空是正常的。
备份新鲜度图表覆盖 barman-cloud 插件和内置方法；其他备份插件需要额外添加它们对应的序列。
Grafana 本身并不随 CNPG 插件一起提供；请自行部署（已使用 Grafana 9.5 验证）。

#Grafana 监控面板

#目录

#内置导出器与 postgres-exporter 对比

#导出器暴露的内容

#安装

#1. 创建带有平台要求标签的 PodMonitor

#2. 将 Grafana 指向平台 Prometheus

#3. 导入监控面板

#图表到指标映射

#已知限制