Plugins Overview

StatusRadar Agent supports 16 monitoring plugins to track databases, web servers, caches, message queues, load balancers, RAID arrays, and other infrastructure services.

What are Plugins?

Plugins extend the base agent functionality to monitor specific services running on your server. Each plugin:

• Collects service-specific metrics (connections, queries, cache hits, etc.)
• Runs independently — one plugin failure doesn't affect others
• Is optional — enable only what you need
• Auto-discovers services — detects whether the service is available
• Reports to the dashboard — metrics appear automatically in the UI

Available Plugins

Databases & Search

Web Servers & Proxies

Caching & Messaging

Containers & Storage

How Plugins Work

Architecture

┌─────────────────────────────────────────┐
│  StatusRadar Agent                      │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  Base Agent (System Metrics)    │   │
│  │  - CPU, Memory, Disk, Network   │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  Plugin Manager                 │   │
│  │  - Loads enabled plugins        │   │
│  │  - Runs collection cycle        │   │
│  │  - Handles errors gracefully    │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐  │
│  │Redis │ │MySQL │ │Nginx │ │Docker│  │
│  │Plugin│ │Plugin│ │Plugin│ │Plugin│  │
│  └──────┘ └──────┘ └──────┘ └──────┘  │
│      │        │        │        │      │
└──────┼────────┼────────┼────────┼──────┘
       │        │        │        │
       ▼        ▼        ▼        ▼
   ┌──────┐┌──────┐┌──────┐┌──────────┐
   │Redis ││MySQL ││Nginx ││Docker    │
   │6379  ││3306  ││80    ││/var/run/ │
   └──────┘└──────┘└──────┘└──────────┘

Collection Cycle

1. Agent starts → Loads configuration from /opt/statusradar/config.env
2. Plugin discovery → Reads the PLUGINS list to see which plugins are enabled
3. Service detection → Tests whether each service is reachable
4. Metric collection → Each plugin collects its metrics
5. Aggregation → Combines all metrics into a single payload
6. API submission → Sends to the StatusRadar API
7. Wait → Sleeps until the next collection interval (default: 300 seconds, minimum 60)
8. Repeat → Returns to step 3

Error Handling

Plugins are isolated from each other:

• One plugin fails → Others continue working
• Service unavailable → Plugin reports status but doesn't crash the agent
• Network error → Agent retries API submission
• Configuration error → Plugin is disabled, others continue

Configuration

The agent is configured through a single shell environment file at /opt/statusradar/config.env. There is no YAML config file. systemd loads it via EnvironmentFile=, so every key is a plain KEY=value line.

The installer writes a base set of keys. Plugins are turned on by listing them in the comma-separated PLUGINS variable, and each plugin reads its own environment variables from the same file.

# /opt/statusradar/config.env
API_TOKEN=your-token-here
API_URL=https://statusradar.dev
INTERVAL=300

# Enabled plugins (comma-separated)
PLUGINS=redis,mysql,nginx,docker,mdadm

# Per-plugin settings
REDIS_HOST=localhost
REDIS_PORT=6379

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=monitor
MYSQL_PASSWORD=secret

NGINX_STATUS_URL=http://127.0.0.1/nginx_status

After editing the file, restart the agent:

sudo systemctl restart statusradar-agent

Enabling Plugins

Method 1: During Installation (Recommended)

Set PLUGINS and any plugin variables as a prefix to the install one-liner. The token is passed via the TOKEN environment variable:

PLUGINS='redis,mysql,nginx,docker' \
REDIS_HOST='localhost' REDIS_PORT='6379' \
TOKEN='your-token-here' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

The installer writes these values into /opt/statusradar/config.env.

Method 2: Manual Configuration

Edit /opt/statusradar/config.env, add the plugin name to PLUGINS, add its environment variables, and restart:

# /opt/statusradar/config.env
PLUGINS=redis,mysql,nginx
REDIS_HOST=localhost
REDIS_PORT=6379

sudo systemctl restart statusradar-agent

The installer auto-populates a few plugin sections (REDIS_*, DOCKER_SOCKET, VM_*, RABBITMQ_*). All other plugin variables must be added to config.env manually, then the agent restarted.

Plugin Environment Variables

Each plugin reads its settings from config.env. The full set of recognized variables:

Configuration Patterns

Local Service Monitoring

The most common setup — monitor services on localhost:

PLUGINS=redis,mysql
REDIS_HOST=localhost
REDIS_PORT=6379
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=monitor
MYSQL_PASSWORD=secret

Remote Service Monitoring

Monitor services on other servers:

PLUGINS=redis,postgresql
REDIS_HOST=cache-server.example.com
REDIS_PORT=6379
REDIS_PASSWORD=secret
POSTGRESQL_HOST=db-server.example.com
POSTGRESQL_PORT=5432
POSTGRESQL_USER=monitor
POSTGRESQL_PASSWORD=secret
POSTGRESQL_DATABASE=postgres

Multiple Instances

Note: The agent monitors one instance per plugin type. To monitor multiple Redis instances, deploy separate agents.

Workaround for multiple databases:

• The MySQL plugin reports server-wide stats via SHOW GLOBAL STATUS.
• The PostgreSQL plugin aggregates all databases via pg_stat_database.
• The MongoDB plugin reports server-wide stats via db.serverStatus().

Plugin Categories

Connection-Based Plugins

Require a network connection to the service:

• Redis (TCP 6379)
• MySQL (TCP 3306)
• PostgreSQL (TCP 5432)
• MongoDB (TCP 27017)
• Memcached (TCP 11211)
• Elasticsearch (HTTP 9200)
• Meilisearch (HTTP 7700)
• RabbitMQ (HTTP 15672 — management API)
• VictoriaMetrics (HTTP 8428)

HTTP Endpoint Plugins

Require an HTTP status endpoint:

• Nginx (/nginx_status)
• Apache (/server-status?auto)
• PHP-FPM (/status)
• HAProxy (/stats;csv)

Command-Based Plugins

Execute system commands:

• Varnish (varnishstat)

Socket-Based Plugins

Access Unix sockets or APIs:

• Docker (/var/run/docker.sock)

File-Based Plugins

Read kernel/proc state directly:

• mdadm (/proc/mdstat)

Plugin Dependencies

Python Packages

Some plugins require an extra Python package:

# Redis plugin
pip install redis

# MySQL plugin
pip install pymysql

# PostgreSQL plugin
pip install psycopg2-binary

# MongoDB plugin
pip install pymongo

# Docker plugin
pip install docker

# Elasticsearch plugin
pip install elasticsearch

The Nginx, Apache, PHP-FPM, HAProxy, Memcached, Meilisearch, VictoriaMetrics, Varnish, and mdadm plugins use only the Python standard library (or local system tools), so they need no extra packages.

Auto-installation: The installer automatically installs required packages for enabled plugins.

Service Requirements

Each plugin requires the target service to be:

1. Installed and running

   sudo systemctl status redis
   sudo systemctl status mysql

2. Accessible from the agent (network, firewall)

   telnet localhost 6379  # Redis
   telnet localhost 3306  # MySQL

3. Configured for monitoring (see plugin-specific docs)

Best Practices

1. Enable Only Needed Plugins

Each plugin adds roughly 10-20 MB RAM and ~2% CPU during collection. Only list plugins for services that are actually running.

2. Use Read-Only Users

MySQL example:

CREATE USER 'monitor'@'localhost' IDENTIFIED BY 'secret';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'monitor'@'localhost';
FLUSH PRIVILEGES;

PostgreSQL example:

CREATE USER monitor WITH PASSWORD 'secret';
GRANT pg_monitor TO monitor;

Benefits:

• Security — the monitoring user can't modify data
• Safety — prevents accidental writes
• Compliance — audit-friendly

3. Secure the Configuration File

config.env holds credentials, so lock it down:

sudo chmod 600 /opt/statusradar/config.env
sudo chown root:root /opt/statusradar/config.env

4. Monitor Plugin Health

Plugin activity is written to the agent log:

sudo tail -f /var/log/statusradar/agent.log

On systemd 240+ the same output is also available via journald:

sudo journalctl -u statusradar-agent -f

5. Test a Plugin Before Deploying

Each plugin can be run directly for a quick check:

cd /opt/statusradar
PLUGINS=redis python3 plugins/redis_plugin.py
PLUGINS=mdadm python3 plugins/mdadm_plugin.py

Expected output:

Plugin name: redis
Enabled: True
Available: True

Metrics collected:
  ...

6. Adjust the Collection Interval

For high-traffic services, consider a longer interval. Set INTERVAL (seconds, minimum 60) in config.env:

INTERVAL=600

Benefits:

• Reduced load on monitored services
• Lower agent resource usage
• Sufficient for most monitoring needs

Performance Impact

Resource Usage by Plugin Count

Collection Duration

Time to collect metrics (typical):

Total collection time: 2-10 seconds (depending on enabled plugins)

Troubleshooting Plugins

Plugin Not Collecting Metrics

Check 1: Is the plugin listed in PLUGINS?

grep '^PLUGINS=' /opt/statusradar/config.env

Check 2: Is the service running?

sudo systemctl status redis
sudo systemctl status mysql

Check 3: Can the agent connect?

telnet localhost 6379               # Redis
curl http://localhost/nginx_status  # Nginx

Check 4: Are the credentials correct?

mysql -u monitor -p -h localhost -e "SHOW STATUS"
psql -U monitor -h localhost -d postgres -c "SELECT version()"

Check 5: Review the agent log

sudo tail -n 100 /var/log/statusradar/agent.log

Common Errors

"Connection refused"

• Service not running: sudo systemctl start redis
• Wrong host/port in config.env
• Firewall blocking the connection

"Authentication failed"

• Wrong username/password in config.env
• User doesn't exist: create the monitoring user
• User lacks permissions: grant the required privileges

"Permission denied"

• Agent can't access the socket: check file permissions
• SELinux blocking access: check audit logs

"Module not found"

• Python package not installed: pip install <package-name>

"Plugin not found"

• Plugin not listed in PLUGINS, or a typo in the name
• Plugin file missing: reinstall the agent

Plugin Updates

Plugins are updated automatically when you update the agent:

curl -s https://statusradar.dev/install-agent.sh | sudo bash -s update

Update process:

1. Downloads the latest agent code
2. Updates all plugin files
3. Restarts the agent service
4. Preserves the existing config.env

Next Steps

Plugin Documentation

Detailed guides for each plugin:

Databases & Search:

• Redis Plugin
• MySQL Plugin
• PostgreSQL Plugin
• MongoDB Plugin
• Elasticsearch Plugin
• Meilisearch Plugin
• VictoriaMetrics Plugin

Web Servers & Proxies:

• Nginx Plugin
• Apache Plugin
• PHP-FPM Plugin
• Varnish Plugin
• HAProxy Plugin

Caching & Messaging:

• Memcached Plugin
• RabbitMQ Plugin

Containers & Storage:

• Docker Plugin
• mdadm Plugin

General Documentation

• Agent Installation
• Agent Configuration
• Agent Troubleshooting
• System Requirements