TroubleshootingCommon Issues & Solutions

Complete troubleshooting guide for pgSentinel monitoring platform. Solutions for common issues, error messages, and performance problems.

Common issues
Database problems
Quick fixes

Common Issues

Solutions for the most frequently encountered problems

Docker & Services

Services not starting

Symptoms
  • docker-compose ps shows Exited status
  • Port conflicts
  • Permission denied errors
Solutions
  • Check if ports are already in use: lsof -i :3000, :8000, :9090
  • Stop conflicting services: docker-compose down
  • Check Docker daemon is running: docker info
  • Verify docker-compose.yml syntax: docker-compose config
  • Check system resources: docker system df
Commands
$ docker-compose down --remove-orphans
$ docker system prune -f
$ docker-compose up -d --force-recreate

Container build failures

Symptoms
  • Build errors in Docker logs
  • npm install failures
  • Permission errors
Solutions
  • Clear Docker build cache: docker builder prune -a
  • Check Dockerfile syntax and dependencies
  • Verify all required files are present
  • Check available disk space
  • Update Docker to latest version
Commands
$ docker-compose build --no-cache
$ docker system prune -a
$ docker-compose up -d --build

Volume mount issues

Symptoms
  • Files not updating
  • Permission denied
  • Empty directories
Solutions
  • Check volume mount paths are correct
  • Verify file permissions on host system
  • Use absolute paths for volume mounts
  • Check Docker volume driver compatibility
Commands
$ docker volume ls
$ docker volume inspect <volume_name>
$ chmod -R 755 ./monitoring

Database Connection

PostgreSQL connection failed

Symptoms
  • Connection refused
  • Authentication failed
  • Database does not exist
Solutions
  • Verify DATABASE_URL in .env file
  • Check PostgreSQL is running: systemctl status postgresql
  • Test connection: psql $DATABASE_URL
  • Verify user permissions and database exists
  • Check firewall and network connectivity
Commands
$ psql -h localhost -U postgres -d postgres
$ systemctl status postgresql
$ netstat -tlnp | grep 5432

pg_stat_statements not enabled

Symptoms
  • No query data in dashboard
  • Extension not found errors
Solutions
  • Enable extension: CREATE EXTENSION pg_stat_statements;
  • Add to postgresql.conf: shared_preload_libraries = 'pg_stat_statements'
  • Restart PostgreSQL after configuration changes
  • Grant permissions: GRANT pg_monitor TO your_user;
Commands
$ psql -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements;"
$ psql -c "GRANT pg_monitor TO postgres;"
$ systemctl restart postgresql

Permission denied errors

Symptoms
  • Access denied to system catalogs
  • Insufficient privileges
Solutions
  • Grant pg_monitor role: GRANT pg_monitor TO your_user;
  • Grant specific table permissions
  • Check user role membership
  • Verify database user has necessary privileges
Commands
$ GRANT pg_monitor TO your_user;
$ GRANT SELECT ON pg_stat_statements TO your_user;
$ \du your_user

Frontend Issues

Dashboard not loading

Symptoms
  • Blank page
  • Loading spinner forever
  • JavaScript errors
Solutions
  • Check browser console for errors
  • Verify API endpoints are accessible
  • Check CORS configuration
  • Clear browser cache and cookies
  • Verify WebSocket connection
Commands
$ curl http://localhost:8000/api/v1/health
$ curl http://localhost:3000
$ docker-compose logs frontend

WebSocket connection failed

Symptoms
  • Real-time updates not working
  • Connection errors in console
Solutions
  • Check WebSocket URL configuration
  • Verify backend is running on correct port
  • Check firewall blocking WebSocket connections
  • Test WebSocket connection manually
Commands
$ wscat -c ws://localhost:8000/ws/live
$ netstat -tlnp | grep 8000
$ docker-compose logs backend

API calls failing

Symptoms
  • Network errors
  • CORS errors
  • 404 Not Found
Solutions
  • Check API base URL configuration
  • Verify backend service is running
  • Check CORS origins configuration
  • Test API endpoints directly
Commands
$ curl -X GET http://localhost:8000/api/v1/health
$ curl -X GET http://localhost:8000/api/v1/status
$ docker-compose logs backend

Monitoring Stack

Prometheus not collecting metrics

Symptoms
  • No metrics in Prometheus UI
  • Targets showing as down
Solutions
  • Check Prometheus configuration file
  • Verify target endpoints are accessible
  • Check Prometheus logs for errors
  • Verify scrape intervals and timeouts
Commands
$ curl http://localhost:9090/api/v1/targets
$ docker-compose logs prometheus
$ curl http://localhost:8000/metrics

Grafana dashboards not loading

Symptoms
  • Empty dashboards
  • Data source errors
  • Login issues
Solutions
  • Check Grafana data source configuration
  • Verify Prometheus is accessible from Grafana
  • Check dashboard JSON syntax
  • Reset Grafana admin password if needed
Commands
$ docker-compose exec grafana grafana-cli admin reset-admin-password admin
$ curl http://localhost:3001/api/health
$ docker-compose logs grafana

No data in dashboards

Symptoms
  • Empty charts
  • No time series data
  • Query errors
Solutions
  • Check Prometheus is collecting metrics
  • Verify time range in Grafana
  • Check query syntax in dashboard panels
  • Verify data source is properly configured
Commands
$ curl "http://localhost:9090/api/v1/query?query=up"
$ curl "http://localhost:9090/api/v1/query_range?query=up&start=2024-01-01T00:00:00Z&end=2024-01-01T23:59:59Z&step=1m"

Error Messages

Understanding and resolving specific error messages

Connection refused

Cannot connect to PostgreSQL database

Common Causes

  • PostgreSQL service not running
  • Wrong host or port in connection string
  • Firewall blocking connection
  • Database server not accepting connections

Solutions

  • Start PostgreSQL service: systemctl start postgresql
  • Check connection string in .env file
  • Verify PostgreSQL is listening on correct port
  • Check firewall rules and network connectivity

Diagnostic Commands

$ systemctl status postgresql
$ netstat -tlnp | grep 5432
$ psql -h localhost -U postgres -d postgres

Permission denied

Insufficient privileges to access database

Common Causes

  • User lacks pg_monitor role
  • Missing table-level permissions
  • Database user not properly configured
  • Role membership issues

Solutions

  • Grant pg_monitor role: GRANT pg_monitor TO your_user;
  • Grant specific table permissions
  • Check user role membership
  • Verify database user configuration

Diagnostic Commands

$ GRANT pg_monitor TO your_user;
$ GRANT SELECT ON pg_stat_statements TO your_user;
$ \du your_user

Extension not found

Required PostgreSQL extensions are missing

Common Causes

  • pg_stat_statements extension not installed
  • Extension not enabled in database
  • PostgreSQL version incompatibility
  • Missing extension files

Solutions

  • Install extension: CREATE EXTENSION pg_stat_statements;
  • Check PostgreSQL version compatibility
  • Verify extension files are present
  • Restart PostgreSQL after installation

Diagnostic Commands

$ CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
$ \dx pg_stat_statements
$ SELECT version();

Port already in use

Required ports are occupied by other services

Common Causes

  • Another service using the same port
  • Previous Docker containers not stopped
  • System service using the port
  • Port conflict in docker-compose.yml

Solutions

  • Stop conflicting services
  • Change port in docker-compose.yml
  • Kill processes using the port
  • Use different port numbers

Diagnostic Commands

$ lsof -i :3000
$ docker-compose down
$ kill -9 <PID>
$ netstat -tlnp | grep :3000

Performance Issues

Troubleshooting performance and optimization problems

Slow dashboard loading

Dashboard takes too long to load or refresh

Possible Causes

  • Large amount of historical data
  • Inefficient database queries
  • Network latency issues
  • Insufficient system resources

Solutions

  • Optimize database queries and add indexes
  • Implement data pagination and limits
  • Use caching for frequently accessed data
  • Increase system resources (CPU, RAM)
  • Consider data retention policies

Monitoring Points

  • Check database query performance
  • Monitor system resource usage
  • Review network latency
  • Analyze API response times

High memory usage

Services consuming excessive memory

Possible Causes

  • Memory leaks in application code
  • Large dataset processing
  • Insufficient garbage collection
  • Too many concurrent connections

Solutions

  • Implement proper memory management
  • Add memory limits to Docker containers
  • Optimize data processing algorithms
  • Implement connection pooling
  • Regular garbage collection

Monitoring Points

  • Monitor container memory usage
  • Check for memory leaks
  • Review garbage collection logs
  • Analyze memory allocation patterns

WebSocket disconnections

Real-time updates frequently disconnect

Possible Causes

  • Network instability
  • WebSocket timeout issues
  • Load balancer configuration
  • Firewall or proxy issues

Solutions

  • Implement WebSocket reconnection logic
  • Adjust timeout settings
  • Check network stability
  • Configure load balancer for WebSockets
  • Implement heartbeat mechanism

Monitoring Points

  • Monitor WebSocket connection stability
  • Check network latency and packet loss
  • Review connection timeout logs
  • Analyze reconnection patterns

Diagnostic Commands

Essential commands for troubleshooting and diagnostics

System Health

$ docker-compose ps

Check status of all services

Shows running/stopped status of containers

$ docker-compose logs --tail=50

View recent logs from all services

Shows last 50 lines of logs from each service

$ docker system df

Check Docker disk usage

Shows space used by Docker images, containers, volumes

$ docker stats --no-stream

Check resource usage of containers

Shows CPU, memory, and network usage per container

Database Diagnostics

$ psql $DATABASE_URL -c "SELECT version();"

Check PostgreSQL version and connection

Shows PostgreSQL version and confirms connection

$ psql $DATABASE_URL -c "\dx"

List installed extensions

Shows all installed PostgreSQL extensions

$ psql $DATABASE_URL -c "SELECT * FROM pg_stat_statements LIMIT 1;"

Test pg_stat_statements access

Shows if pg_stat_statements is working and accessible

$ psql $DATABASE_URL -c "\du"

List database users and roles

Shows all database users and their role memberships

API Testing

$ curl http://localhost:8000/api/v1/health

Test backend health endpoint

Returns system health status and service states

$ curl http://localhost:8000/api/v1/status

Get detailed system status

Returns detailed system metrics and status

$ curl http://localhost:8000/metrics

Check Prometheus metrics endpoint

Returns raw Prometheus metrics in text format

$ curl http://localhost:9090/api/v1/targets

Check Prometheus targets

Shows status of all monitored targets

Still Need Help?

If you're still experiencing issues, here are additional resources to help you resolve them.

Configuration Guide

Review configuration options and settings

API Reference

Check API endpoints and responses

Report Issue

Open an issue on GitHub