Troubleshooting Guide #

Comprehensive solutions for common Server Monitor plugin issues.

Quick Diagnostics #

System Health Check #

Run these commands to verify your setup:

# 1. Check plugin installation
ls -la plugins/albrightlabs/servermonitor/

# 2. Verify database tables
php artisan tinker
>>> Schema::hasTable('servers')
>>> Schema::hasTable('server_logs')

# 3. Test queue workers
php artisan queue:work --once

# 4. Check API endpoints
curl -s "https://yoursite.com/api/servermonitor/worker-status/YOUR_API_KEY"

# 5. Verify cron jobs
crontab -l | grep servermonitor

Log Locations #

Key log files to check:

Laravel logs: storage/logs/laravel.log
Worker logs: storage/logs/worker-*.log
Web server logs: /var/log/nginx/error.log or /var/log/apache2/error.log
System logs: /var/log/syslog

Common Issues #

1. Servers Not Being Checked #

Symptoms:

"Last checked" timestamps are old
No status updates in server list
No notifications being sent

Diagnosis:

# Check if cron jobs are running
tail -f /var/log/syslog | grep CRON

# Check queue workers
sudo supervisorctl status | grep servermonitor

# Check recent job logs
tail -f storage/logs/worker-premium.log

Solutions:

Missing Cron Jobs:

# Add required cron jobs
crontab -e

# Add these lines:
* * * * * curl -s https://yoursite.com/api/servermonitor/check/premium/YOUR_API_KEY
*/5 * * * * curl -s https://yoursite.com/api/servermonitor/check/free/YOUR_API_KEY

Workers Not Running:

# Check supervisor status
sudo supervisorctl status

# Restart workers
sudo supervisorctl restart servermonitor-premium:*
sudo supervisorctl restart servermonitor-free:*

# Check worker configuration
sudo nano /etc/supervisor/conf.d/servermonitor-workers.conf

Invalid API Key:

# Verify API key in .env
grep SERVER_MONITOR_API_KEY .env

# Test API manually
curl "https://yoursite.com/api/servermonitor/check/premium/YOUR_ACTUAL_KEY"

2. Notifications Not Sending #

Symptoms:

Status changes occur but no emails/SMS received
Communication logs empty
No notification-related log entries

Email Issues:

Check Mail Configuration:

# Test email sending
php artisan tinker
>>> Mail::raw('Test', function($m) { $m->to('test@example.com')->subject('Test'); });

# Check mail logs
tail -f storage/logs/laravel.log | grep -i mail

Common Email Fixes:

# Verify these settings in .env
MAIL_DRIVER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=alerts@yourdomain.com

SMS Issues:

Check Twilio Configuration:

# Test Twilio credentials
php artisan tinker
>>> $client = new \Twilio\Rest\Client(env('TWILIO_SID'), env('TWILIO_TOKEN'));
>>> $client->messages->create('+1234567890', ['from' => env('TWILIO_NUMBER'), 'body' => 'Test']);

Common SMS Fixes:

# Verify Twilio settings
TWILIO_SID=your-account-sid
TWILIO_TOKEN=your-auth-token
TWILIO_NUMBER=+1234567890

Notification Settings:

Verify users have notification preferences configured
Check that users belong to the correct organization
Ensure organization is on appropriate plan for SMS

3. High Queue Backlog #

Symptoms:

Worker performance dashboard shows warnings
Long delays between server checks
SLA compliance below 95%

Diagnosis:

# Check queue sizes
php artisan queue:work --once --queue=premium
php artisan queue:work --once --queue=free

# For Redis queues
redis-cli llen queues:premium
redis-cli llen queues:free

Solutions:

Add More Workers:

# Edit supervisor config
sudo nano /etc/supervisor/conf.d/servermonitor-workers.conf

# Increase numprocs for affected queues
[program:servermonitor-premium]
numprocs=4  # Increase from 2

# Apply changes
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart servermonitor-premium:*

Clear Stuck Jobs:

# View failed jobs
php artisan queue:failed

# Clear all jobs (CAUTION: This removes all pending jobs)
php artisan queue:clear

# Restart all workers
sudo supervisorctl restart all

4. Uptime Calculations Wrong #

Symptoms:

Uptime percentages seem incorrect
Uptime not updating after status changes
Servers showing 0% or 100% incorrectly

Diagnosis:

# Check if server needs recalculation
php artisan tinker
>>> $server = \Albrightlabs\ServerMonitor\Models\Server::find(123);
>>> $server->require_calculation;
>>> $server->logs()->count();

Solutions:

Force Recalculation:

# Recalculate specific server
curl "https://yoursite.com/api/servermonitor/calculate/server/123/YOUR_API_KEY"

# Recalculate all servers
curl "https://yoursite.com/api/servermonitor/calculate/all/YOUR_API_KEY"

# Or via console
php artisan tinker
>>> $server = \Albrightlabs\ServerMonitor\Models\Server::find(123);
>>> $server->updatePercentUptime();

Check Uptime Calculation Job:

# Verify hourly cron job exists
crontab -l | grep calculate

# Add if missing
0 * * * * curl -s https://yoursite.com/api/servermonitor/calculate/YOUR_API_KEY

5. Permission and Access Issues #

Symptoms:

"Access denied" messages
Users can't see servers
Settings pages not accessible

User Permissions:

# Check user organization and admin status
php artisan tinker
>>> $user = \Backend\Models\User::where('email', 'user@example.com')->first();
>>> $user->organization_id;
>>> $user->is_organization_admin;

Server Visibility:

Users only see servers from their organization
Albright Labs staff see all servers
Check server organization assignment

6. Database Issues #

Symptoms:

Migration errors
Missing tables
Foreign key constraint errors

Check Database Connection:

# Test connection
php artisan tinker
>>> \DB::connection()->getPdo();

# Check tables exist
>>> Schema::hasTable('servers');
>>> Schema::hasTable('server_logs');

Re-run Migrations:

# Run migrations with verbose output
php artisan october:migrate --verbose

# Check specific plugin migrations
ls plugins/albrightlabs/servermonitor/updates/

7. Performance Issues #

Symptoms:

Slow dashboard loading
Long queue processing times
High server resource usage

Database Optimization:

# Check database size
php artisan tinker
>>> \DB::table('server_logs')->count();
>>> \DB::table('server_check_logs')->count();

# Purge old logs
curl "https://yoursite.com/api/servermonitor/purge-logs/YOUR_API_KEY"

Queue Optimization:

Switch from database to Redis queue driver
Add more worker processes
Monitor worker memory usage

Debug Mode #

Enable Debug Logging #

# Enable application debug
APP_DEBUG=true

# Enable notification debug
SERVERMONITOR_NOTIFICATION_DEBUG=true

# Enable queue debug
QUEUE_FAILED_DRIVER=database

Reading Debug Logs #

Notification Debug:

# Watch notification logs
tail -f storage/logs/laravel.log | grep "Albright Heartbeat"

Queue Debug:

# Watch queue processing
tail -f storage/logs/worker-premium.log
tail -f storage/logs/worker-free.log

Database Query Debug:

# Enable query logging
php artisan tinker
>>> \DB::enableQueryLog();
>>> # Perform action
>>> \DB::getQueryLog();

Emergency Procedures #

Complete System Reset #

CAUTION: This will clear all monitoring data

# 1. Stop all workers
sudo supervisorctl stop servermonitor-premium:*
sudo supervisorctl stop servermonitor-free:*
sudo supervisorctl stop servermonitor-calculations:*

# 2. Clear all queues
php artisan queue:clear
php artisan queue:flush

# 3. Reset database (DESTRUCTIVE)
php artisan migrate:rollback --path=plugins/albrightlabs/servermonitor/updates
php artisan october:migrate

# 4. Restart workers
sudo supervisorctl start servermonitor-premium:*
sudo supervisorctl start servermonitor-free:*
sudo supervisorctl start servermonitor-calculations:*

Service Recovery #

Quick Recovery Steps:

# 1. Restart application
php artisan cache:clear
php artisan config:clear
php artisan route:clear

# 2. Restart queue workers
sudo supervisorctl restart all

# 3. Test critical endpoints
curl "https://yoursite.com/api/servermonitor/worker-status/YOUR_API_KEY"

# 4. Verify monitoring resumes
tail -f storage/logs/worker-premium.log

Getting Help #

Information to Gather #

Before contacting support, collect:

System Information:

php --version
php artisan --version
cat /etc/os-release

Plugin Status:

ls -la plugins/albrightlabs/
php artisan plugin:list | grep ServerMonitor

Error Logs:

tail -50 storage/logs/laravel.log
sudo supervisorctl status

Configuration:

# Sanitized .env (remove sensitive data)
grep -E "(QUEUE|TWILIO|MAIL|SERVER_MONITOR)" .env

Support Channels #

Email Support: support@albrightlabs.com

Include in Support Request:

Clear description of the issue
Steps to reproduce
Error messages and logs
System information
Screenshots if relevant

Response Times:

Critical issues: 2-4 hours
Standard issues: 24-48 hours
Feature requests: 1-2 weeks

Self-Help Resources #

Worker Performance Dashboard - Real-time system health
Configuration Guide - Settings verification
API Reference - Manual testing procedures
Community Forums - Search for similar issues

Prevention #

Monitoring Your Monitoring #

Set up secondary monitoring for the monitoring system itself:

# External uptime monitor for your server monitor
# Use services like Uptime Robot or Pingdom to monitor:
# - https://yoursite.com/api/servermonitor/worker-status/YOUR_API_KEY
# - Worker performance dashboard accessibility
# - Email delivery success rates

Regular Maintenance #

Weekly:

Check worker performance dashboard
Verify email/SMS delivery
Review communication logs

Monthly:

Update server list (remove decommissioned)
Review plan usage and limits
Check log retention and cleanup

Quarterly:

Rotate API keys
Update Twilio credentials if needed
Review notification recipient list

Backup Procedures #

Configuration Backup:

# Backup configuration files
cp .env .env.backup
cp plugins/albrightlabs/servermonitor/config/config.php config.backup.php

# Backup supervisor configuration
cp /etc/supervisor/conf.d/servermonitor-workers.conf servermonitor-workers.conf.backup

Database Backup:

# Backup only ServerMonitor tables
mysqldump --tables servers server_logs server_check_logs dispatch_logs alert_logs servermonitor_notification_settings > servermonitor_backup.sql

Previous: ← Performance | Next: Support →