Agent Not Reporting Data

When your Server Scout agent stops sending data to the dashboard, there are several potential causes to investigate. This guide will walk you through the systematic troubleshooting process to identify and resolve the issue.

Initial Service Check

Start by verifying whether the agent service is running on your server:

systemctl status scout-agent

If the service is stopped or failed, you'll see this in the output. To restart the service:

sudo systemctl restart scout-agent

If the service fails to start or keeps stopping, proceed to check the logs for error messages.

Examining Agent Logs

The agent logs provide detailed information about what's preventing data transmission. Use journalctl to view the most recent log entries:

journalctl -u scout-agent -f

The -f flag follows the log output in real-time, allowing you to see new entries as they appear. For historical logs without following:

journalctl -u scout-agent --since "1 hour ago"

Look for error messages, connection failures, or authentication issues in the log output.

Common Causes and Solutions

Network and Firewall Issues

The most frequent cause of reporting failures is network connectivity problems. The agent requires HTTPS access to app.serverscout.ie on port 443.

Test connectivity manually:

curl -I https://app.serverscout.ie

If this fails, check your firewall rules and ensure outbound HTTPS traffic is permitted. For servers behind corporate firewalls, you may need to configure proxy settings or request that app.serverscout.ie be whitelisted.

API Key Problems

An expired, invalid, or incorrectly configured API key will prevent data transmission. Check your API key configuration in /opt/scout-agent/agent.env:

sudo cat /opt/scout-agent/agent.env

You should see MONITORURL and MONITORKEY entries. Verify that the API key matches what's shown in your Server Scout dashboard under the server's installation page. If you've recently regenerated your API key, update the MONITOR_KEY value in agent.env and restart the service:

sudo systemctl restart scout-agent

Disk Space Issues

When the disk becomes full, the agent cannot write to its spool directory, preventing data collection and transmission. Check available disk space:

df -h

The agent stores its spool files in /opt/scout-agent/. If your root partition is full, clear some space and restart the agent service.

Understanding Data Spooling

Server Scout's agent includes built-in resilience through automatic data spooling. When connectivity issues occur, the agent doesn't simply discard monitoring data. Instead, it:

1. Queues collected metrics locally in the spool directory
2. Continues collecting system metrics during the outage
3. Automatically retransmits queued data once connectivity resumes

This means temporary network interruptions won't result in data loss. You may notice a gap in real-time monitoring, but historical data will appear once the connection is restored.

The spooling mechanism can handle outages lasting several hours, depending on available disk space. Monitor the spool directory size during extended outages:

du -sh /opt/scout-agent/

Agent Reinstallation

If troubleshooting steps don't resolve the issue, reinstalling the agent may be necessary. This is particularly useful when configuration files become corrupted or when upgrading from very old versions.

First, stop and remove the existing installation:

sudo systemctl stop scout-agent
sudo systemctl disable scout-agent
sudo rm -rf /opt/scout-agent
sudo rm -f /etc/systemd/system/scout-agent.service
sudo systemctl daemon-reload

Then reinstall using the install command from your Server Scout dashboard's server installation page:

curl -sL https://app.serverscout.ie/agent/install.sh | bash -s -- --url https://app.serverscout.ie --key YOUR_API_KEY

The installation script will create fresh configuration files at /opt/scout-agent/agent.env and start the service automatically.

Monitoring Resolution

Once you've addressed the underlying issue, monitor the logs for a few minutes to confirm data transmission has resumed:

journalctl -u scout-agent -f

Look for successful transmission messages, and check your Server Scout dashboard to verify that fresh data appears within the next monitoring cycle.