Plugins Overview

StatusRadar Agent supports 16 monitoring plugins to track databases, web servers, caches, message queues, 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 if service is available
• Reports to dashboard - metrics appear automatically in UI

Available Plugins

Databases

Web Servers & Proxies

Caching & Messaging

Containers

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/agent.yaml
2. Plugin discovery → Checks which plugins are enabled
3. Service detection → Tests if each service is reachable
4. Metric collection → Each plugin collects its metrics
5. Aggregation → Combines all metrics into single payload
6. API submission → Sends to StatusRadar API
7. Wait → Sleeps until next collection interval (default: 5 minutes)
8. Repeat → Goes 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 agent
• ✅ Network error → Agent retries API submission
• ✅ Configuration error → Plugin disabled, others continue

Enabling Plugins

Method 1: During Installation (Recommended)

# Install with specific plugins
PLUGINS='redis,mysql,nginx,docker' \
TOKEN='your-token-here' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Method 2: Manual Configuration

Edit /opt/statusradar/config/agent.yaml:

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379

  mysql:
    enabled: true
    host: localhost
    port: 3306
    user: monitor
    password: secret

  nginx:
    enabled: true
    status_url: http://127.0.0.1/nginx_status

Restart agent:

sudo systemctl restart statusradar-agent

Method 3: Environment Variables

# Enable via environment variables
export REDIS_ENABLED=true
export REDIS_HOST=localhost
export REDIS_PORT=6379

sudo systemctl restart statusradar-agent

Configuration Patterns

Local Service Monitoring

Most common setup - monitor services on localhost:

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379

  mysql:
    enabled: true
    host: localhost
    port: 3306
    user: monitor
    password: secret

Remote Service Monitoring

Monitor services on other servers:

plugins:
  redis:
    enabled: true
    host: cache-server.example.com
    port: 6379
    password: secret

  postgresql:
    enabled: true
    host: db-server.example.com
    port: 5432
    user: monitor
    password: secret
    database: postgres

Multiple Instances

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

Workaround for multiple databases:

• MySQL plugin can query multiple databases via SHOW GLOBAL STATUS
• PostgreSQL plugin can query all databases via pg_stat_database
• MongoDB plugin can query all databases via db.serverStatus()

SSL/TLS Connections

For services supporting encryption:

plugins:
  redis:
    enabled: true
    host: redis.example.com
    port: 6380
    ssl: true
    password: secret

  postgresql:
    enabled: true
    host: postgres.example.com
    port: 5432
    ssl_mode: require  # Options: disable, require, verify-ca, verify-full
    user: monitor
    password: secret

Plugin Categories

Connection-Based Plugins

Require network connection to 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 HTTP status endpoint:

• Nginx (/nginx_status)
• Apache (/server-status)
• PHP-FPM (/status)
• HAProxy (/stats)

Command-Based Plugins

Execute system commands:

• Varnish (varnishstat)

Socket-Based Plugins

Access Unix sockets or APIs:

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

Plugin Dependencies

Python Packages

Plugins require specific Python packages:

# 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

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
   # etc.

2. Accessible from 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 ~10-20 MB RAM and ~2% CPU during collection.

Don't:

plugins:
  redis:
    enabled: true  # But Redis not installed - wastes resources checking

Do:

plugins:
  redis:
    enabled: true  # Only if Redis is 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 - monitoring user can't modify data
• Safety - prevents accidental writes
• Compliance - audit-friendly

3. Secure Configuration File

# Protect credentials
sudo chmod 600 /opt/statusradar/config/agent.yaml
sudo chown root:root /opt/statusradar/config/agent.yaml

4. Monitor Plugin Health

Check plugin status in agent logs:

sudo journalctl -u statusradar-agent -f

Expected output:

INFO: Plugin redis: Metrics collected successfully
INFO: Plugin mysql: Metrics collected successfully
INFO: Plugin nginx: Metrics collected successfully

Error indicators:

ERROR: Plugin redis: Connection refused
WARNING: Plugin mysql: Authentication failed

5. Test Before Deploying

Test plugin manually before enabling:

cd /opt/statusradar
python3 plugins/redis_plugin.py
python3 plugins/mysql_plugin.py

Expected output:

Plugin: redis
Enabled: True
Available: True

Collecting metrics...
{
  "used_memory": 1234567,
  "connected_clients": 5,
  ...
}

6. Adjust Collection Interval

For high-traffic services, consider longer intervals:

agent:
  interval: 600  # 10 minutes instead of 5

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 plugin enabled?

grep -A5 "plugin_name:" /opt/statusradar/config/agent.yaml

Check 2: Is service running?

sudo systemctl status redis
sudo systemctl status mysql
# etc.

Check 3: Can agent connect?

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

Check 4: Are credentials correct?

# Test MySQL credentials
mysql -u monitor -p -h localhost -e "SHOW STATUS"

# Test PostgreSQL credentials
psql -U monitor -h localhost -d postgres -c "SELECT version()"

Check 5: Review agent logs

sudo journalctl -u statusradar-agent -n 100 --no-pager | grep plugin_name

Common Errors

"Connection refused"

• Service not running: sudo systemctl start redis
• Wrong host/port in configuration
• Firewall blocking connection

"Authentication failed"

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

"Permission denied"

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

"Module not found"

• Python package not installed: pip install package-name
• Virtual environment not activated

"Plugin not found"

• Plugin file missing: reinstall agent
• Typo in plugin name in configuration

Plugin Updates

Plugins are updated automatically when you update the agent:

# Update agent (includes all plugins)
curl -sL https://statusradar.dev/install-agent.sh | sudo bash -s update

Update process:

1. Downloads latest agent code
2. Updates all plugin files
3. Restarts agent service
4. Existing configuration preserved

Next Steps

Plugin Documentation

Detailed guides for each plugin:

Databases:

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

Web Servers:

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

Caching & Messaging:

• Memcached Plugin
• RabbitMQ Plugin

Containers:

• Docker Plugin

General Documentation

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