Agent Configuration

The StatusRadar Agent is configured via a YAML file located at /opt/statusradar/config/agent.yaml. This guide covers all configuration options and best practices.

Configuration File Location

/opt/statusradar/config/agent.yaml

Basic Structure

api:
  url: https://api.statusradar.dev
  token: your-agent-token-here

agent:
  hostname: my-server-01
  interval: 300
  timeout: 30

plugins:
  # Plugin configurations here

API Configuration

`api.url`

Type: String Required: Yes Default: https://api.statusradar.dev

The StatusRadar API endpoint. Use the production endpoint unless you're running a self-hosted instance.

api:
  url: https://api.statusradar.dev

`api.token`

Type: String Required: Yes Default: None

Your unique agent authentication token. Get this from the Add Server page in the dashboard.

Security: Keep this token secret. Anyone with this token can send metrics to your account.

api:
  token: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Agent Configuration

`agent.hostname`

Type: String Required: No Default: System hostname

Custom hostname for the server. If not specified, uses the system hostname.

agent:
  hostname: production-web-01

`agent.interval`

Type: Integer (seconds) Required: No Default: 300 (5 minutes)

How often the agent collects and sends metrics. Minimum: 60 seconds.

agent:
  interval: 300  # Collect every 5 minutes

Recommended values:

Production servers: 300 (5 minutes)
Development servers: 600 (10 minutes)
High-frequency monitoring: 60 (1 minute)

`agent.timeout`

Type: Integer (seconds) Required: No Default: 30

API request timeout. Increase if you have slow network connections.

agent:
  timeout: 30

Plugin Configuration

Plugins are configured under the plugins section. Each plugin has its own configuration block.

General Plugin Structure

plugins:
  plugin_name:
    enabled: true
    # Plugin-specific options

Available Plugins

Redis Plugin

Monitor Redis cache/database instances.

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379
    password: ''          # Optional: Redis password
    ssl: false            # Optional: Use SSL/TLS
    database: 0           # Optional: Database number

Required: Redis 4.0+

Metrics Collected:

Memory usage, fragmentation
Command statistics
Client connections
Keyspace statistics
Replication status
Persistence metrics

MySQL Plugin

Monitor MySQL or MariaDB database servers.

plugins:
  mysql:
    enabled: true
    host: localhost
    port: 3306
    user: monitor
    password: secret
    database: ''          # Optional: Test database

Required: MySQL 5.7+ or MariaDB 10.3+

Setup:

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

Metrics Collected:

Connection statistics
Query performance
Table locks
InnoDB metrics
Replication status

PostgreSQL Plugin

Monitor PostgreSQL database servers.

plugins:
  postgresql:
    enabled: true
    host: localhost
    port: 5432
    user: postgres
    password: secret
    database: postgres
    ssl_mode: disable     # Options: disable, require, verify-ca, verify-full

Required: PostgreSQL 10+

Setup:

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

Metrics Collected:

Connection pool statistics
Transaction rates
Lock statistics
Table and index statistics
Replication lag
Cache hit ratios

MongoDB Plugin

Monitor MongoDB database servers.

plugins:
  mongodb:
    enabled: true
    host: localhost
    port: 27017
    username: ''          # Optional
    password: ''          # Optional
    database: admin
    auth_source: admin    # Optional

Required: MongoDB 4.0+

Metrics Collected:

Operation counters
Connection statistics
Memory usage
Replication status
WiredTiger cache
Lock statistics

Nginx Plugin

Monitor Nginx web server.

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

Required: Nginx with stub_status module enabled

Nginx Configuration:

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Metrics Collected:

Active connections
Requests per second
Reading/writing/waiting states

Apache Plugin

Monitor Apache HTTP Server.

plugins:
  apache:
    enabled: true
    status_url: http://127.0.0.1/server-status?auto

Required: Apache with mod_status enabled

Apache Configuration:

<Location "/server-status">
    SetHandler server-status
    Require ip 127.0.0.1
</Location>

Metrics Collected:

Worker statistics
Request rate
Bytes transferred
CPU load
Idle/busy workers

PHP-FPM Plugin

Monitor PHP-FPM process manager.

plugins:
  php_fpm:
    enabled: true
    status_url: http://127.0.0.1:8080/status?json

Required: PHP-FPM with status page enabled

PHP-FPM Configuration:

; /etc/php/8.2/fpm/pool.d/www.conf
pm.status_path = /status

Nginx Configuration:

location ~ ^/(status|ping)$ {
    access_log off;
    allow 127.0.0.1;
    deny all;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Metrics Collected:

Active processes
Idle processes
Total processes
Slow requests
Listen queue

Memcached Plugin

Monitor Memcached cache server.

plugins:
  memcached:
    enabled: true
    host: localhost
    port: 11211

Required: Memcached 1.4+

Metrics Collected:

Cache hits/misses
Memory usage
Current connections
Items stored
Evictions
Get/set operations

RabbitMQ Plugin

Monitor RabbitMQ message broker.

plugins:
  rabbitmq:
    enabled: true
    host: localhost
    port: 15672           # Management API port
    username: guest
    password: guest
    protocol: http        # Options: http, https

Required: RabbitMQ 3.8+ with management plugin

Setup:

rabbitmq-plugins enable rabbitmq_management

Metrics Collected:

Queue statistics
Message rates
Consumer counts
Node memory
Disk usage
Connection counts

Docker Plugin

Monitor Docker containers and resources.

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock

Required: Docker 20.10+

Permissions:

# Add statusradar user to docker group
usermod -aG docker root

Metrics Collected:

Container count (running/stopped)
CPU usage per container
Memory usage per container
Network I/O
Block I/O
Container states

Elasticsearch Plugin

Monitor Elasticsearch search engine.

plugins:
  elasticsearch:
    enabled: true
    host: localhost
    port: 9200
    protocol: http        # Options: http, https
    username: ''          # Optional: For auth
    password: ''          # Optional: For auth

Required: Elasticsearch 7.0+

Metrics Collected:

Cluster health
Node statistics
Index statistics
JVM metrics
Thread pool
Query performance

Meilisearch Plugin

Monitor Meilisearch search engine.

plugins:
  meilisearch:
    enabled: true
    host: localhost
    port: 7700
    protocol: http
    api_key: ''           # Optional: Master key

Required: Meilisearch 1.0+ with metrics enabled

Meilisearch Startup:

meilisearch --experimental-enable-metrics
# Or set environment variable
export MEILI_EXPERIMENTAL_ENABLE_METRICS=true

Metrics Collected:

HTTP request count
Response times
Database size
Index count
Document count
Search queue size

Varnish Plugin

Monitor Varnish HTTP cache.

plugins:
  varnish:
    enabled: true
    varnishstat_path: /usr/bin/varnishstat  # Optional

Required: Varnish 6.0+

Permissions:

# Ensure agent can read varnish stats
usermod -aG varnish root

Metrics Collected:

Cache hits/misses
Backend connections
Client connections
Object statistics
Thread statistics

HAProxy Plugin

Monitor HAProxy load balancer.

plugins:
  haproxy:
    enabled: true
    stats_url: http://localhost:8081/stats;csv
    username: ''          # Optional: Stats auth
    password: ''          # Optional: Stats auth

Required: HAProxy 2.0+

HAProxy Configuration:

listen stats
    bind *:8081
    stats enable
    stats uri /stats
    stats refresh 30s

Metrics Collected:

Frontend/backend statistics
Session rates
Queue lengths
Response times
Server status

VictoriaMetrics Plugin

Monitor VictoriaMetrics time-series database.

plugins:
  victoriametrics:
    enabled: true
    url: http://localhost:8428

Required: VictoriaMetrics 1.80+

Metrics Collected:

Active series
Ingestion rate
Query performance
Storage size
Memory usage
Uptime

Environment Variables

All configuration options can be overridden using environment variables:

# API Configuration
export STATUSRADAR_API_URL="https://api.statusradar.dev"
export STATUSRADAR_TOKEN="your-token-here"

# Agent Configuration
export STATUSRADAR_HOSTNAME="custom-hostname"
export STATUSRADAR_INTERVAL="300"
export STATUSRADAR_TIMEOUT="30"

# Plugin-specific
export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD="secret"

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

export POSTGRESQL_HOST="localhost"
export POSTGRESQL_PORT="5432"
export POSTGRESQL_USER="postgres"
export POSTGRESQL_PASSWORD="secret"
export POSTGRESQL_DATABASE="postgres"

export NGINX_STATUS_URL="http://127.0.0.1/nginx_status"
export APACHE_STATUS_URL="http://127.0.0.1/server-status?auto"
export PHP_FPM_STATUS_URL="http://127.0.0.1:8080/status?json"

export MEMCACHED_HOST="localhost"
export MEMCACHED_PORT="11211"

export MONGODB_HOST="localhost"
export MONGODB_PORT="27017"

export RABBITMQ_HOST="localhost"
export RABBITMQ_PORT="15672"
export RABBITMQ_USERNAME="guest"
export RABBITMQ_PASSWORD="guest"

export DOCKER_SOCKET="/var/run/docker.sock"

Configuration Examples

Minimal Configuration

api:
  url: https://api.statusradar.dev
  token: your-token-here

agent:
  interval: 300

Production Web Server

api:
  url: https://api.statusradar.dev
  token: your-token-here

agent:
  hostname: production-web-01
  interval: 300
  timeout: 30

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

  php_fpm:
    enabled: true
    status_url: http://127.0.0.1:9000/status?json

  redis:
    enabled: true
    host: localhost
    port: 6379

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

Database Server

api:
  url: https://api.statusradar.dev
  token: your-token-here

agent:
  hostname: production-db-01
  interval: 300

plugins:
  postgresql:
    enabled: true
    host: localhost
    port: 5432
    user: monitor
    password: secret
    database: postgres

  redis:
    enabled: true
    host: localhost
    port: 6379

Container Host

api:
  url: https://api.statusradar.dev
  token: your-token-here

agent:
  hostname: docker-host-01
  interval: 300

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock

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

Best Practices

Security

Protect Configuration File:

chmod 600 /opt/statusradar/config/agent.yaml
chown root:root /opt/statusradar/config/agent.yaml

Use Read-Only Database Users:
- Create dedicated monitoring users with minimal permissions
- Never use root/admin accounts
Restrict Plugin Access:
- Use localhost/127.0.0.1 for local services
- Configure firewalls for remote services
- Use SSL/TLS when available

Performance

Adjust Collection Interval:
- Production: 300 seconds (5 minutes)
- Development: 600 seconds (10 minutes)
- Don't go below 60 seconds unless necessary
Enable Only Needed Plugins:
- Disable unused plugins to reduce overhead
- Each plugin adds ~5-10MB RAM

Monitor Agent Resources:

systemctl status statusradar-agent
journalctl -u statusradar-agent -f

Reliability

Test Configuration:

# Test before restarting
python3 /opt/statusradar/statusradar-agent.py --test

Use Systemd:
- Agent restarts automatically on failure
- Starts on boot
- Proper logging
Monitor Agent Health:
- Check dashboard for last update time
- Set up alerts for agent offline

Reloading Configuration

After changing the configuration, restart the agent:

sudo systemctl restart statusradar-agent

Check if changes applied:

sudo journalctl -u statusradar-agent -n 50 --no-pager

Next Steps

On this page

Configuration File Location
Basic Structure
API Configuration
`api.url`
`api.token`
Agent Configuration
`agent.hostname`
`agent.interval`
`agent.timeout`
Plugin Configuration
General Plugin Structure
Available Plugins
Redis Plugin
MySQL Plugin
PostgreSQL Plugin
MongoDB Plugin
Nginx Plugin
Apache Plugin
PHP-FPM Plugin
Memcached Plugin
RabbitMQ Plugin
Docker Plugin
Elasticsearch Plugin
Meilisearch Plugin
Varnish Plugin
HAProxy Plugin
VictoriaMetrics Plugin
Environment Variables
Configuration Examples
Minimal Configuration
Production Web Server
Database Server
Container Host
Best Practices
Security
Performance
Reliability
Reloading Configuration
Next Steps