Plugin Metrics Explained

Server Scout's plugin system extends beyond standard Linux metrics to monitor specific applications and hosting control panels. Unlike the core agent that exclusively reads from /proc and /sys filesystems, plugins execute external commands to gather application-specific data, providing deep insights into services like cPanel, DirectAdmin, Plesk, and backup solutions.

How Plugins Work

Plugins are optional Bash scripts stored in /opt/scout-agent/plugins.d/ that automatically detect and monitor specific software installations. Each plugin follows a standardised pattern:

1. Detection — The plugin checks whether its target software is installed
2. Collection — If detected, it gathers metrics using the application's APIs or command-line tools
3. Output — Metrics are formatted as JSON and transmitted alongside core system metrics

This separation allows Server Scout to maintain its ultra-lightweight core whilst providing comprehensive monitoring for complex applications that require external command execution.

Plugin Architecture

Auto-Detection System

Each plugin implements a detect() function that performs lightweight checks to determine if the target software is present. For example:

• cPanel — Checks for /usr/local/cpanel/version and WHM installation
• DirectAdmin — Looks for /usr/local/directadmin/ directory structure
• Plesk — Verifies /usr/local/psa/ installation and plesk command availability
• JetBackup — Tests for JetBackup 5 CLI tools in standard paths

When the agent starts, it scans all plugins in /plugins.d/, runs their detection logic, and loads only those whose target software is found. This ensures zero overhead for unused plugins.

Data Registration

Active plugins register with the core agent using a standardised metadata structure:

This metadata enables the dashboard to present plugin data with appropriate branding and visual consistency.

Collection Timing and Performance

Glacial Tier Execution

Plugins run exclusively on the Glacial tier (every hour), much less frequently than core metrics. This design choice reflects several important considerations:

Performance Impact — Unlike core metrics that read virtual filesystems, plugins must execute external commands (whmapi1, plesk, backup utilities). These operations involve disk I/O, process forking, and network requests that could significantly impact system performance if run frequently.

Data Stability — Application-level metrics like account counts, backup statuses, and SSL certificate states change slowly. Hourly collection provides adequate monitoring granularity whilst minimising resource consumption.

API Rate Limiting — Many hosting control panels implement API throttling. Hourly collection ensures Server Scout remains well within these limits.

Available Plugins

cPanel Plugin

Detection: Presence of WHM installation and /usr/local/cpanel/version

Key Metrics:

The cPanel plugin leverages WHM's API (whmapi1) to gather comprehensive hosting metrics, providing visibility into account management, security certificate status, and service health.

DirectAdmin Plugin

Detection: /usr/local/directadmin/ directory and DirectAdmin daemon

Key Metrics:

DirectAdmin's plugin focuses on user management and bandwidth monitoring, essential metrics for hosting providers managing multiple client accounts.

Plesk Plugin

Detection: Plesk installation at /usr/local/psa/ and plesk CLI availability

Key Metrics:

Plesk's plugin provides comprehensive hosting metrics through the plesk command-line interface, covering subscriptions, databases, and maintenance status.

JetBackup Plugin

Detection: JetBackup 5 CLI tools and configuration files

Key Metrics:

JetBackup monitoring ensures backup reliability by tracking job success rates, storage consumption, and identifying stale backups that might indicate configuration issues.

Plugin Metrics in the Dashboard

API Integration

Plugin metrics integrate seamlessly with Server Scout's history API using dot-notation syntax:

plugin_name.metric_name

Examples:

• cpanel.accounts — cPanel account count over time
• jetbackup.backup_age — JetBackup age trends
• plesk.subscriptions — Plesk subscription growth

This naming convention allows plugin metrics to coexist with core system metrics whilst maintaining clear separation and avoiding naming conflicts.

Dashboard Presentation

The Server Scout dashboard presents plugin data in a dedicated section on each server's detail page. Plugin metrics receive the same historical analysis as core metrics, with time-series charts showing:

• 1 hour — Raw hourly data points
• 6 hours — No averaging (glacial tier already provides 1-hour resolution)
• 24 hours — Daily trend analysis
• 7 days — Weekly patterns and anomaly detection

Plugin-specific branding (icons, colours) helps administrators quickly identify different hosting platforms and backup solutions across their server fleet.

Plugin Checksums and Updates

Automatic Updates

Server Scout tracks SHA-256 checksums of all plugin scripts, enabling automatic updates without manual intervention:

1. Checksum Verification — During daily check-ins, agents report plugin checksums to the platform
2. Update Detection — The dashboard compares agent checksums against current plugin versions
3. Automatic Download — Agents with outdated plugins automatically download new versions
4. Seamless Deployment — Updates apply during the next plugin execution cycle

This mechanism ensures all servers receive plugin improvements, bug fixes, and support for new software versions without administrator involvement.

Version Tracking

The dashboard maintains a complete audit trail of plugin versions across your server fleet, helping identify servers that might have missed updates or experienced download failures.

Custom Plugin Development

Plugin Template

Advanced users can develop custom plugins following Server Scout's standardised pattern:

#!/bin/bash

# Plugin metadata
PLUGIN_KEY="myapp"
PLUGIN_LABEL="My Application"
PLUGIN_ICON="custom-icon"
PLUGIN_COLOR="#336699"

detect() {
    # Return 0 if target software is detected, 1 otherwise
    [[ -f /opt/myapp/config.conf ]] && return 0
    return 1
}

collect() {
    # Gather metrics and output JSON
    local metric1=$(myapp-cli --status | grep "connections" | awk '{print $2}')
    local metric2=$(myapp-cli --performance | grep "throughput" | awk '{print $3}')
    
    cat << EOF
{
    "connections": ${metric1:-0},
    "throughput_mbps": ${metric2:-0}
}
EOF
}

Development Guidelines

Performance Considerations — Custom plugins must be mindful of execution time and system impact. Avoid operations that could block for extended periods or consume significant CPU/memory resources.

Error Handling — Implement robust error handling to prevent plugin failures from affecting core agent operation. Always provide sensible defaults for metrics that cannot be collected.

JSON Output — Ensure all numeric metrics are output as valid JSON numbers (not strings) to enable proper dashboard charting and alerting.

Installation

Place custom plugin scripts in /opt/scout-agent/plugins.d/ with executable permissions. The agent automatically detects new plugins during its next startup cycle.

Why Plugins Are Separate

The plugin architecture serves several critical purposes in Server Scout's design philosophy:

Performance Isolation — External command execution is inherently expensive compared to reading virtual filesystems. Separating plugins prevents application monitoring from impacting the ultra-lightweight core agent performance.

Modularity — Servers only load plugins for software they actually run, avoiding unnecessary overhead and complexity for services that aren't present.

Update Flexibility — Plugin updates can be deployed independently of core agent updates, enabling rapid response to application changes without requiring full agent upgrades.

Extensibility — The standardised plugin API enables monitoring of virtually any application that provides command-line interfaces or APIs, future-proofing Server Scout's monitoring capabilities.

This architectural separation ensures Server Scout maintains its core promise of lightweight, high-frequency system monitoring whilst providing comprehensive application-level insights where needed.