Introduction

PostgreSQL is one of the most widely used open-source relational databases. In production environments, it is commonly deployed as a cluster to provide high availability, read scalability, and failover protection.

While monitoring individual PostgreSQL instances is useful, it does not provide a complete view of overall cluster health. Instana’s PostgreSQL Cluster monitoring introduces a unified cluster view that aggregates metrics across all nodes, helping you understand performance, capacity, and availability at a glance.

Why Cluster-Level Monitoring Matters

In PostgreSQL, a cluster is formed when multiple nodes share the same cluster_name configuration.

This can represent:

• A single primary node (single-node cluster)
• A primary node with one or more replicas (multi-node cluster)

With node-by-node monitoring, it is difficult to quickly answer:

• Is the cluster healthy overall?
• How many replicas are available for failover?
• What is the total workload across all nodes?
• How many active connections exist across the cluster?

Instana automatically groups nodes with the same cluster_name and provides cluster-level visibility without manual configuration.

Key Metrics in the PostgreSQL Cluster Dashboard

The cluster dashboard displays five aggregated metrics that provide an instant health overview.

• Database Count: Total number of databases across the cluster.
  Helps track database growth and detect unexpected database creation.
• Replica Count: Number of standby nodes in the cluster. Confirms your high-availability configuration and redundancy level.
• Total Active Connections: Sum of active connections across all nodes.
  Helps prevent connection exhaustion and understand connection pool usage.
• Total Database Size: Combined storage used by all databases across the cluster. Supports storage forecasting and capacity planning.
• Transaction Rate: Commits and rollbacks per second across the entire cluster. Represents overall workload and helps detect performance anomalies.
  
  

Node-Level Visibility

The cluster view includes a Nodes Monitored (N) table that shows the following items:

• Node name (clickable for drill-down)
• Role (Primary / Replica)
• PostgreSQL version
• Health status

How Node Health Is Calculated

Node health is derived from connection utilization:

• Healthy → Normal connection usage
• Degraded → Sustained high connection usage
• Unhealthy → Critical connection saturation

This helps detect connection pressure before it impacts applications.

The health shown in the table is at the node-level, not at the cluster-level.

Replication Metrics (Replica Nodes)

Replication metrics are available when you drill down into replica nodes.

Replication Delay (Bytes)

Amount of WAL data the replica is behind the primary.

A value of 0 bytes means the replica is fully synchronized and ready for failover.

Replication Delay (Seconds)

Time lag behind the primary.
Low values indicate up-to-date replicas suitable for read traffic and failover.

Per-Database Metrics

Each node provides database-level insights, including:

• Committed and rolled-back transactions
• Cache hit ratio
• Active connections per database
• Database size
• Tuple operations
• Standby conflicts (on replicas)

These metrics help identify database-specific performance issues.

How Clusters Are Formed in Instana

Instana automatically creates a cluster when it detects PostgreSQL nodes with the same cluster_name.

Steps

1. Configure the same cluster name on all nodes.

cluster_name = 'my_cluster'

2. Install the Instana agent.

3. Instana auto-discovers and groups the nodes.

Locating postgresql.conf

The location of postgresql.conf depends on your installation method and operating system.

Common locations:

• Linux (package installation):
  /etc/postgresql/<version>/main/postgresql.conf
• Linux (manual install):
  <data_directory>/postgresql.conf
• macOS (Homebrew):
  /usr/local/var/postgres/postgresql.conf or
  /opt/homebrew/var/postgres/postgresql.conf
• Docker:
  Inside the container data directory

To find the active configuration file, run:

SHOW config_file;

Getting Started

Prerequisites

• Instana agent installed on all PostgreSQL nodes
• PostgreSQL sensor enabled
• Monitoring user with required privileges

Configuration Example

Set the cluster name in postgresql.conf:

cluster_name = 'production_cluster'

Instana agent configuration:

# PostgreSQL
com.instana.plugin.postgresql:
  enabled: true
  user: '<user>'
  password: '<password>'
  database: '<database>'
  poll_rate: 1

Restart PostgreSQL and the Instana agent.
The cluster will be discovered automatically.

Troubleshooting

Cluster Not Appearing

Check the following:

• The cluster_name value is configured and identical on all PostgreSQL nodes
• Instana agent is running on every PostgreSQL host
• The agent can connect to PostgreSQL (network and port reachable)
• The monitoring user has the required privileges.

Authentication Configuration (Important)

All PostgreSQL nodes in the cluster  primary and replicas  must use the same monitoring credentials, and those credentials must match the Instana agent configuration.

This means:

• The same username must exist on both primary and replica nodes
• The same password must be configured for that user on all nodes
• The Instana agent must use those exact credentials.

If the credentials differ between nodes, the agent cannot collect metrics from replicas, and they will not appear in the cluster view.

With PostgreSQL Cluster monitoring in Instana, you can:

• View your entire cluster in a single dashboard
• Instantly verify primary and replica status
• Monitor total workload and connection usage
• Drill down into any node for detailed metrics
• Understand replication health for failover readiness

All of this is automatically discovered, with no complex configuration.

Conclusion

Instana’s PostgreSQL Cluster monitoring provides a single, unified view of your database environment, enabling you to:

• Detect issues quickly
• Validate high-availability configurations
• Monitor cluster-wide performance
• Troubleshoot replication and workload imbalances

By combining automatic discovery, aggregated cluster metrics, and node-level drill-down, Instana gives you the visibility needed to operate PostgreSQL clusters with confidence.

#Documentation
#Database

#BusinessObservability
#Infrastructure