Force-Refreshing Agent Data Collection

The Server Scout agent collects metrics on different schedules—fast metrics every minute, medium metrics every five minutes, and slower metrics at longer intervals. Sometimes you'll need to force immediate collection of all metrics, particularly after configuration changes or during troubleshooting.

Using the Force-Refresh Flag

The simplest way to trigger an immediate data collection is using the built-in refresh flag:

/opt/scout-agent/scout-agent.sh --refresh

This command sends a SIGUSR1 signal to the running agent process, instructing it to collect all metrics immediately. The command returns quickly and doesn't interrupt the agent's normal operation.

What Happens During Force-Refresh

When a force-refresh is triggered, the agent immediately runs all collection tiers:

• Fast metrics (CPU usage, memory, network stats)
• Medium metrics (disk I/O, process counts)
• Slow metrics (installed packages, service status)
• Glacial metrics (hardware information)
• Daily metrics (hostname, OS version, system configuration)

All collected data is then transmitted to Server Scout on the next transmission cycle, typically within 30-60 seconds.

When to Use Force-Refresh

After Configuration Changes

Whenever you modify the agent configuration file (/opt/scout-agent/scout-agent.conf), use force-refresh to ensure the changes take effect immediately:

sudo nano /opt/scout-agent/scout-agent.conf
/opt/scout-agent/scout-agent.sh --refresh

After Plugin Management

When enabling or disabling plugins, force-refresh ensures the changes are reflected in your Server Scout dashboard:

# After enabling a new plugin
/opt/scout-agent/scout-agent.sh --refresh

Troubleshooting Verification

After resolving agent issues, force-refresh helps verify the agent is collecting and sending data properly:

# Check if agent responds to commands
/opt/scout-agent/scout-agent.sh --refresh
# Then monitor logs for confirmation
tail -f /var/log/scout-agent.log

Immediate Reporting of Daily Metrics

Daily metrics like hostname changes, OS updates, or hardware modifications normally report once per day. Force-refresh makes them available immediately:

# After system updates or hostname changes
/opt/scout-agent/scout-agent.sh --refresh

Manual Signal Methods

You can also send the SIGUSR1 signal directly to the agent process using standard Linux tools.

Using kill Command

kill -USR1 $(pidof scout-agent.sh)

This finds the agent's process ID and sends the signal directly.

Using systemctl

If you're running the agent as a systemd service:

systemctl kill -s USR1 scout-agent

This method works regardless of how the service was started and is particularly useful in containerised environments.

Monitoring the Force-Refresh

When the agent receives the signal, it logs the event. You'll see this message in the agent logs:

Force refresh requested

To monitor this in real-time:

tail -f /var/log/scout-agent.log | grep -i "force refresh"

Important Considerations

Force-refresh is completely non-destructive. It doesn't restart the agent, interrupt ongoing collections, or affect the agent's configuration. The agent continues its normal scheduling after completing the forced collection.

The process is also safe to run multiple times. If you trigger force-refresh whilst another collection is running, the agent queues the request and processes it appropriately.

Troubleshooting Force-Refresh

If the force-refresh command appears to have no effect:

1. Verify the agent is running: ps aux | grep scout-agent
2. Check agent logs for error messages: tail -20 /var/log/scout-agent.log
3. Ensure you have appropriate permissions to send signals to the process

Force-refresh is an essential tool for maintaining responsive monitoring and ensuring your Server Scout dashboard reflects the current state of your systems promptly.