Add checkTitle field to all report JSONs

NikolayS · NikolayS · commit 866d6a77ef2e · 2025-12-01T15:40:04.000-08:00
diff --git a/README.md b/README.md
@@ -202,6 +202,52 @@ Get a complete monitoring setup with demo data in under 2 minutes.
 ./postgres_ai health
 ```
 
+## 📋 Checkup reports
+
+postgres_ai monitoring generates automated health check reports based on [postgres-checkup](https://gitlab.com/postgres-ai/postgres-checkup). Each report has a unique check ID and title:
+
+### A. General / Infrastructural
+| Check ID | Title |
+|----------|-------|
+| A001 | System information |
+| A002 | Version information |
+| A003 | Postgres settings |
+| A004 | Cluster information |
+| A005 | Extensions |
+| A006 | Postgres setting deviations |
+| A007 | Altered settings |
+| A008 | Disk usage and file system type |
+
+### D. Monitoring / Troubleshooting
+| Check ID | Title |
+|----------|-------|
+| D004 | pg_stat_statements and pg_stat_kcache settings |
+
+### F. Autovacuum, Bloat
+| Check ID | Title |
+|----------|-------|
+| F001 | Autovacuum: current settings |
+| F004 | Autovacuum: heap bloat (estimated) |
+| F005 | Autovacuum: index bloat (estimated) |
+
+### G. Performance / Connections / Memory-related settings
+| Check ID | Title |
+|----------|-------|
+| G001 | Memory-related settings |
+
+### H. Index analysis
+| Check ID | Title |
+|----------|-------|
+| H001 | Invalid indexes |
+| H002 | Unused indexes |
+| H004 | Redundant indexes |
+
+### K. SQL query analysis
+| Check ID | Title |
+|----------|-------|
+| K001 | Globally aggregated query metrics |
+| K003 | Top-50 queries by total_time |
+
 ## 🌐 Access points
 
 After running quickstart:
diff --git a/reporter/postgres_reports.py b/reporter/postgres_reports.py
@@ -1594,13 +1594,89 @@ def format_report_data(self, check_id: str, data: Dict[str, Any], host: str = "t
 
         template_data = {
             "checkId": check_id,
+            "checkTitle": self.get_check_title(check_id),
             "timestamptz": now.isoformat(),
             "nodes": hosts,
             "results": results
         }
 
         return template_data
 
+    def get_check_title(self, check_id: str) -> str:
+        """
+        Get the human-readable title for a check ID.
+        
+        Args:
+            check_id: The check identifier (e.g., "H004")
+            
+        Returns:
+            Human-readable title for the check
+        """
+        # Mapping based on postgres-checkup README
+        # https://gitlab.com/postgres-ai/postgres-checkup
+        check_titles = {
+            "A001": "System information",
+            "A002": "Postgres major version",
+            "A003": "Postgres settings",
+            "A004": "Cluster information",
+            "A005": "Extensions",
+            "A006": "Postgres setting deviations",
+            "A007": "Altered settings",
+            "A008": "Disk usage and file system type",
+            "A010": "Data checksums, wal_log_hints",
+            "A011": "Connection pooling. pgbouncer",
+            "A012": "Anti-crash checks",
+            "A013": "Postgres minor version",
+            "B001": "SLO/SLA, RPO, RTO",
+            "B002": "File system, mount flags",
+            "B003": "Full backups / incremental",
+            "B004": "WAL archiving",
+            "B005": "Restore checks, monitoring, alerting",
+            "C001": "SLO/SLA",
+            "C002": "Sync/async, Streaming / wal transfer; logical decoding",
+            "C003": "SPOFs; standby with traffic",
+            "C004": "Failover",
+            "C005": "Switchover",
+            "C006": "Delayed replica",
+            "C007": "Replication slots. Lags. Standby feedbacks",
+            "D001": "Logging settings",
+            "D002": "Useful Linux tools",
+            "D003": "List of monitoring metrics",
+            "D004": "pg_stat_statements and pg_stat_kcache settings",
+            "D005": "track_io_timing, auto_explain",
+            "D006": "Recommended DBA toolsets",
+            "D007": "Postgres-specific tools for troubleshooting",
+            "E001": "WAL/checkpoint settings, IO",
+            "E002": "Checkpoints, bgwriter, IO",
+            "F001": "Autovacuum: current settings",
+            "F002": "Autovacuum: transaction ID wraparound check",
+            "F003": "Autovacuum: dead tuples",
+            "F004": "Autovacuum: heap bloat (estimated)",
+            "F005": "Autovacuum: index bloat (estimated)",
+            "F006": "Precise heap bloat analysis",
+            "F007": "Precise index bloat analysis",
+            "F008": "Autovacuum: resource usage",
+            "G001": "Memory-related settings",
+            "G002": "Connections and current activity",
+            "G003": "Timeouts, locks, deadlocks",
+            "G004": "Query planner",
+            "G005": "I/O settings",
+            "G006": "Default_statistics_target",
+            "H001": "Invalid indexes",
+            "H002": "Unused indexes",
+            "H003": "Non-indexed foreign keys",
+            "H004": "Redundant indexes",
+            "J001": "Capacity planning",
+            "K001": "Globally aggregated query metrics",
+            "K002": "Workload type",
+            "K003": "Top-50 queries by total_time",
+            "L001": "Table sizes",
+            "L002": "Data types being used",
+            "L003": "Integer out-of-range risks in PKs",
+            "L004": "Tables without PK/UK",
+        }
+        return check_titles.get(check_id, f"Check {check_id}")
+
     def get_setting_unit(self, setting_name: str) -> str:
         """Get the unit for a PostgreSQL setting."""
         units = {
