Overview
Use this guide to send CloudNativePG cluster metrics to SigNoz with the OpenTelemetry Collector. Monitor cluster health, connections, throughput, cache, replication, WAL and archiving, checkpoints, and storage.
Prerequisites
- A CloudNativePG cluster running in Kubernetes
- An OpenTelemetry Collector deployed in the same cluster. See OpenTelemetry Collector on Kubernetes to get started
- An instance of SigNoz (Cloud or Self-Hosted)
How it works
Each CloudNativePG instance exposes Prometheus-format metrics with the cnpg_ prefix on port 9187, path /metrics. The instance pods carry the cnpg.io/cluster label and a container port named metrics. The Collector discovers those pods, scrapes the endpoint, and ships the metrics to SigNoz over OTLP.
For the full metric list, see the CloudNativePG monitoring reference.
Steps
Step 1: Configure the Collector
Add a scrape job that filters for CloudNativePG instance pods, a resource processor that tags the metrics with service.name, and a dedicated pipeline. Merge this into your existing Collector config:
receivers:
prometheus/cnpg:
config:
scrape_configs:
- job_name: cloudnative-pg
scrape_interval: 30s
kubernetes_sd_configs:
- role: pod
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_cnpg_io_cluster]
action: keep
regex: .+
- source_labels: [__meta_kubernetes_pod_container_port_name]
action: keep
regex: metrics
- source_labels: [__meta_kubernetes_pod_name]
target_label: pod
- source_labels: [__meta_kubernetes_namespace]
target_label: namespace
processors:
resource/cnpg:
attributes:
- key: service.name
value: cloudnative-pg
action: upsert
exporters:
otlphttp:
endpoint: "https://ingest.<region>.signoz.cloud:443"
headers:
signoz-ingestion-key: "<your-ingestion-key>"
service:
pipelines:
metrics/cnpg:
receivers: [prometheus/cnpg]
processors: [resource/cnpg, batch]
exporters: [otlphttp]
Verify these values:
<region>: your SigNoz Cloud region<your-ingestion-key>: your SigNoz Cloud ingestion key
The Collector needs ClusterRole permissions for Kubernetes pod discovery. The OpenTelemetry Collector on Kubernetes guide covers the required RBAC setup.
Step 2: Restart the Collector
kubectl rollout restart deployment/<collector-deployment> -n <collector-namespace>
Validate
- Open Metrics Explorer in SigNoz.
- Search for metrics that start with
cnpg_. - Look for metrics such as
cnpg_collector_up.
Troubleshooting
No cnpg_ metrics in SigNoz
- Cause: the Collector cannot discover the CloudNativePG pods, or it lacks RBAC permissions.
- Fix: confirm the Collector has
ClusterRoleaccess for pod discovery, and confirm the instance pods carry thecnpg.io/clusterlabel with a container port namedmetrics. - Verify: search for
cnpg_collector_upin Metrics Explorer.
Metrics endpoint uses TLS
- Cause: the cluster sets
.spec.monitoring.tls.enabled: true, so the metrics endpoint serves HTTPS. - Fix: set
scheme: httpson the scrape job and configuretls_configwith the cluster's CA in the Prometheus receiver. - Verify: the scrape job stops logging connection or protocol errors.
Per-database metrics are missing
- Cause: the
cnpg_pg_stat_database_*metrics change after queries run against the database. - Fix: confirm clients are connecting and running queries against the database.
- Verify:
cnpg_pg_stat_database_xact_commitincrements between scrapes.
Next Steps
- Import the prebuilt CloudNativePG dashboard.
- Read how to Set up Alerts in SigNoz.
Get Help
If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.
