Managing Patroni Clusters and Logging

Patroni is a powerful high-availability (HA) solution for PostgreSQL. Efficient management and robust logging are essential to maintain the health and transparency of your database cluster. This guide outlines key Patroni cluster operations and introduces structured JSON logging to simplify monitoring and troubleshooting.

1. Monitoring the Cluster

To check the state of your PostgreSQL cluster, Patroni provides simple command-line utilities via patronictl.

Viewing Cluster Status

Run the following to get a summary of your cluster:

patronictl -c /etc/patroni.yml list

Sample Output:

+ Cluster: patronicluster (*******************) ----+----+-----------+
| Member      | Host            | Role    | State   | TL | Lag in MB |
+-------------+-----------------+---------+---------+----+-----------+
| pg-patroni1 | xxx.xxx.xxx.xxx | Leader  | running |  1 |           |
| pg-patroni2 | xxx.xxx.xxx.xxx | Replica | running |  1 |         0 |
+-------------+-----------------+---------+---------+----+-----------+

Alternatively, for a hierarchical topology view:

patronictl -c /etc/patroni.yml topology

This provides a clearer picture of replicas following a specific leader.

2. Maintenance Mode

To temporarily disable Patroni’s automatic cluster management:

patronictl -c /etc/patroni.yml pause

To resume management:

patronictl -c /etc/patroni.yml resume

During maintenance mode, failovers and promotions are suppressed, allowing safe manual operations or upgrades.

3. Manual Failover and Switchover

Manual Failover

Use failover when the current leader is unreachable:

patronictl -c /etc/patroni.yml failover --candidate pg-patroni2

Scheduled Switchover

Perform a graceful handover when the cluster is healthy:

patronictl -c /etc/patroni.yml switchover --candidate pg-patroni2

You’ll be prompted to confirm the operation and optionally schedule a time.

4. Viewing Cluster History

To review past failover or switchover events:

patronictl -c /etc/patroni.yml history

This logs the timeline ID, log sequence number, reason, and new leader after a transition.

5. Configuring JSON Logging for Better Observability

Structured logging is essential for integration with centralized log systems like ELK, Graylog, or Loki. JSON format makes logs machine-readable and easier to analyze.

Install Required Module

Ensure python-json-logger is installed:

# Install pip (if not already installed)
sudo dnf install -y python3-pip

# Install python-json-logger
/usr/bin/python3 -m pip install python-json-logger

Edit `patroni.yml`

Update your logging configuration:

log:
  level: DEBUG                        # Log level (INFO, DEBUG, WARNING, etc.)
  dir: /var/log/patroni               # Log directory
  file: /var/log/patroni/patroni.log  # Log file path
  file_size: 1073741824               # Maximum log file size (1GB)
  type: json                          # Log format (set to json for structured logging)

Then restart Patroni:

sudo systemctl restart patroni.service
# Do not forget to apply replica server fristly.

Verify Logging

Tail the log file to check for structured JSON entries:

# If your file size exceeds 1GB it will continue by opening a new file with other file name as 1 at the end
tail -f /var/log/patroni/patroni.log
# You can change file_size parameter suitable that your requirements.

These logs are suitable for integration with logging pipelines.

Working with systemd and journalctl

Use systemd to manage the Patroni service:

# Check status
sudo systemctl status patroni.service

# Start Patroni
sudo systemctl start patroni.service

# Restart Patroni
sudo systemctl restart patroni.service

Use journalctl to view real-time or historical logs:

# Show logs for Patroni
sudo journalctl -u patroni.service

# Follow logs in real-time
sudo journalctl -u patroni.service -f

# View logs for a specific time window
sudo journalctl -u patroni.service --since &amp;amp;quot;1 hour ago&amp;amp;quot;

# Show logs with JSON formatting (for better readability in some tools)
sudo journalctl -u patroni.service --output=json-pretty

Tips for Troubleshooting with Logs

Look for messages related to:
Cluster state transitions (e.g., failover, switchover)
Connection issues with PostgreSQL
Failures in DCS communication (e.g., with Etcd, Consul, or ZooKeeper)
Use grep to filter logs:

sudo journalctl -u patroni.service | grep -i &amp;amp;quot;failover&amp;amp;quot;

6. Conclusion

Managing a Patroni cluster is straightforward with patronictl, while adding JSON log support enhances your ability to monitor and troubleshoot issues. With structured logs and system tools like journalctl, administrators gain deeper visibility into cluster behavior, enabling faster response and better system health.