Writing a Custom Monitoring Plugin

What Are Server Scout Plugins?

Server Scout plugins are custom Bash scripts that extend the monitoring capabilities of the agent. They allow you to monitor specific services, applications, or metrics that aren't covered by the default monitoring suite. Plugins are automatically detected and loaded by the agent, making it easy to add bespoke monitoring for your unique infrastructure needs.

Plugin File Structure

Plugins are standard Bash scripts with a .sh extension, placed in the /opt/scout-agent/plugins.d/ directory. Each plugin must implement three required functions and set one configuration variable.

Required Components

PLUGIN_TIER Variable Set this to control how frequently your plugin's collect() function runs:

• fast - Every 5 seconds
• medium - Every 30 seconds
• slow - Every 5 minutes
• glacial - Every hour
• daily - Every 24 hours

detect() Function Returns 0 if the software or service your plugin monitors is present, 1 otherwise. This typically involves checking for binaries, configuration files, or running processes.

collect() Function Gathers metrics and stores them in variables. This function is called at the frequency specified by PLUGIN_TIER.

json() Function Outputs collected data as valid JSON. This data will be nested under your plugin's name in the agent payload sent to Server Scout.

Basic Plugin Template

Here's a minimal plugin skeleton that monitors a hypothetical service:

#!/bin/bash

# Set collection frequency
PLUGIN_TIER="medium"

# Global variables for metrics
service_status=""
connection_count=0

detect() {
    # Check if the service binary exists and is running
    if command -v myservice >/dev/null 2>&1 && pgrep myservice >/dev/null; then
        return 0  # Service detected
    else
        return 1  # Service not found
    fi
}

collect() {
    # Gather service status
    if systemctl is-active myservice >/dev/null 2>&1; then
        service_status="active"
    else
        service_status="inactive"
    fi
    
    # Count active connections (example)
    connection_count=$(netstat -an | grep :8080 | grep ESTABLISHED | wc -l)
}

json() {
    # Output valid JSON
    cat << EOF
{
    "status": "$service_status",
    "connections": $connection_count,
    "timestamp": $(date +%s)
}
EOF
}

Installation Steps

1. Create your plugin file in /opt/scout-agent/plugins.d/:

``bash sudo nano /opt/scout-agent/plugins.d/myservice.sh ``

1. Make it executable:

``bash sudo chmod +x /opt/scout-agent/plugins.d/myservice.sh ``

1. Restart the Scout agent:

``bash sudo systemctl restart scout-agent ``

Testing Your Plugin

After installation, verify your plugin is working correctly:

Check Plugin Loading

sudo journalctl -u scout-agent | grep -i plugin

Look for messages like "Plugin loaded: myservice" to confirm successful detection.

Monitor for Errors

sudo journalctl -u scout-agent -f

Watch the live logs for any error messages related to your plugin.

Validate JSON Output Test your plugin's JSON function manually:

cd /opt/scout-agent/plugins.d/
source ./myservice.sh
detect && collect && json

Best Practices

• Error Handling: Always include proper error checking in your functions
• Performance: Keep collect() lightweight, especially for fast/medium tier plugins
• JSON Validity: Ensure your JSON output is properly formatted and escaped
• Resource Usage: Avoid operations that might block or consume excessive resources
• Logging: Use descriptive variable names and add comments for maintainability

Troubleshooting

If your plugin isn't working:

1. Check file permissions - ensure the script is executable
2. Validate syntax - run bash -n yourplugin.sh to check for syntax errors
3. Test functions individually - source the script and test each function manually
4. Review agent logs - look for specific error messages in the journal

Your custom plugin data will appear in the Server Scout dashboard under the Plugins section once successfully loaded and collecting data.