HAProxy Plugin

Monitor HAProxy load balancer with comprehensive metrics covering frontend/backend statistics, server health, session rates, queues, and connection tracking.

Overview

The HAProxy plugin collects detailed metrics from HAProxy stats socket including:

• Frontend Metrics - Incoming connections, requests, session rate, errors
• Backend Metrics - Backend connections, queue depth, response times
• Server Health - Server status, health checks, up/down transitions
• Session Statistics - Active sessions, session rate, connection limits
• Queue Metrics - Current queue, max queue, queue time
• Traffic Statistics - Bytes in/out, request/response rates

Requirements

HAProxy Version

• Minimum: HAProxy 1.8
• Recommended: HAProxy 2.4 or later
• Tested with: HAProxy 2.0, 2.4, 2.6, 2.8

HAProxy Stats Socket

Required: Stats socket must be enabled in HAProxy configuration.

Python Dependencies

No additional Python packages required - uses standard library socket.

Socket Access

The agent needs read access to HAProxy stats socket.

Configuration

Basic Configuration

plugins:
  haproxy:
    enabled: true
    socket_path: /run/haproxy/admin.sock

With HTTP Stats Page

plugins:
  haproxy:
    enabled: true
    stats_url: http://localhost:8404/stats;csv
    username: admin
    password: password

All Configuration Options

plugins:
  haproxy:
    enabled: true                              # Enable/disable plugin
    socket_path: /run/haproxy/admin.sock      # Stats socket path
    stats_url: ""                              # HTTP stats URL (alternative)
    username: ""                               # HTTP auth username
    password: ""                               # HTTP auth password
    timeout: 10                                # Socket/HTTP timeout (seconds)

Environment Variables

Configuration can be overridden with environment variables:

export HAPROXY_SOCKET="/run/haproxy/admin.sock"
export HAPROXY_STATS_URL="http://localhost:8404/stats;csv"

HAProxy Setup

Installation

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install haproxy

# Start service
sudo systemctl start haproxy
sudo systemctl enable haproxy

CentOS/RHEL:

sudo yum install haproxy

# Start service
sudo systemctl start haproxy
sudo systemctl enable haproxy

Enable Stats Socket

Edit HAProxy configuration:

sudo nano /etc/haproxy/haproxy.cfg

Add stats socket to global section:

global
    stats socket /run/haproxy/admin.sock mode 660 level admin
    stats timeout 30s

Or enable HTTP stats page:

listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s
    stats auth admin:password

Restart HAProxy:

sudo systemctl restart haproxy

Grant Socket Access

Agent runs as root by default - has access to socket.

For non-root agent:

# Add user to haproxy group
sudo usermod -aG haproxy statusradar

# Or change socket permissions
# In haproxy.cfg:
# stats socket /run/haproxy/admin.sock mode 666 level admin

Collected Metrics

Frontend Metrics

Backend Metrics

Server Metrics

Metadata Metrics

Dashboard Metrics

The StatusRadar dashboard displays:

Overview Card

• Active Sessions - Current frontend sessions
• Backend Status - Healthy backends count
• Queue Depth - Current backend queue
• Request Rate - Requests per second

Frontend Traffic Chart

• Incoming requests rate
• Session rate
• Bytes in/out

Backend Health Chart

• Backend status (UP/DOWN)
• Queue depth over time
• Connection errors

Server Status Table

• Server name and status
• Current sessions
• Queue depth
• Health check status
• Response time

Session Rate Chart

• Frontend session rate
• Backend session rate
• Max sessions limit

Error Rate Chart

• Connection errors
• Response errors
• Denied requests

Installation

Quick Install

PLUGINS='haproxy' \
TOKEN='your-agent-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Install on Existing Agent

1. Enable HAProxy stats socket (see above)

2. Configure agent:

   sudo nano /opt/statusradar/config/agent.yaml

   Add:

   plugins:
     haproxy:
       enabled: true
       socket_path: /run/haproxy/admin.sock

3. Restart agent:

   sudo systemctl restart statusradar-agent

4. Verify:

   sudo journalctl -u statusradar-agent -n 50 --no-pager | grep haproxy

   Expected:

   INFO: Plugin haproxy: Metrics collected successfully
   INFO: Plugin haproxy: 3 frontends, 5 backends, 2 servers UP

Testing

Manual Plugin Test

cd /opt/statusradar
python3 plugins/haproxy_plugin.py

Expected Output:

Plugin: haproxy
Enabled: True
Available: True

Collecting metrics...
{
  "frontends": {
    "http": {
      "sessions": 45,
      "sessions_rate": 12.5,
      "requests_total": 123456
    }
  },
  "backends": {
    "web_servers": {
      "sessions": 42,
      "queue_current": 0,
      "status": "UP"
    }
  },
  "servers": {
    "web1": {
      "status": "UP",
      "sessions": 21,
      "check_status": "L7OK"
    }
  }
}

Test HAProxy Socket

# Query stats via socket
echo "show stat" | sudo socat stdio /run/haproxy/admin.sock

# Show info
echo "show info" | sudo socat stdio /run/haproxy/admin.sock

# Show servers state
echo "show servers state" | sudo socat stdio /run/haproxy/admin.sock

Troubleshooting

Plugin Not Collecting Metrics

Check 1: Is HAProxy running?

sudo systemctl status haproxy

Check 2: Is stats socket enabled?

grep "stats socket" /etc/haproxy/haproxy.cfg

Check 3: Can agent access socket?

sudo ls -la /run/haproxy/admin.sock
echo "show info" | sudo socat stdio /run/haproxy/admin.sock

Check 4: Check agent logs

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

Common Errors

"Stats socket not found"

Error:

ERROR: Plugin haproxy: Stats socket not found at /run/haproxy/admin.sock

Solution:

Enable stats socket in haproxy.cfg:

global
    stats socket /run/haproxy/admin.sock mode 660 level admin

Restart HAProxy:

sudo systemctl restart haproxy

"Permission denied"

Error:

ERROR: Plugin haproxy: Permission denied accessing stats socket

Solution:

# Add agent user to haproxy group
sudo usermod -aG haproxy statusradar

# Or change socket permissions (less secure)
# In haproxy.cfg:
# stats socket /run/haproxy/admin.sock mode 666 level admin

"socat not found"

Error:

ERROR: Plugin haproxy: socat command not found

Solution:

# Install socat
sudo apt-get install socat  # Ubuntu/Debian
sudo yum install socat      # CentOS/RHEL

Performance Impact

On HAProxy

Minimal impact:

• Stats socket reads from shared memory
• No request processing impact
• Response time: < 10ms

Benchmark:

• Overhead: < 0.01% CPU
• No measurable performance degradation

On Agent

Resource usage:

• Memory: +8 MB
• CPU: +2% during collection
• Network: +1 KB per collection

Collection time: < 0.1 seconds

Use Cases

1. Backend Health Monitoring

Monitor:

• Server status (UP/DOWN)
• Health check failures
• Server downtime

Alert on:

• Server DOWN
• Health check failures
• Frequent up/down transitions

2. Queue Monitoring

Monitor:

• Backend queue depth
• Server queue depth
• Queue time

Alert on:

• Queue depth > 0 (backend saturated)
• Queue growing
• Max queue reached

3. Session Tracking

Monitor:

• Current sessions vs max
• Session rate
• Session limit reached

Alert on:

• Sessions > 80% of max
• Session rate spike
• Denied connections

4. Error Rate Monitoring

Monitor:

• Connection errors
• Response errors
• Retries and redispatches

Alert on:

• Error rate > 1%
• Connection errors increasing
• High retry rate

Best Practices

1. Configure Health Checks

backend web_servers
    option httpchk GET /health HTTP/1.1
    http-check expect status 200

    server web1 10.0.0.10:80 check inter 5s fall 3 rise 2
    server web2 10.0.0.11:80 check inter 5s fall 3 rise 2

Parameters:

• inter: Check interval (5s)
• fall: Failures before marking DOWN (3)
• rise: Successes before marking UP (2)

2. Set Session Limits

frontend http
    maxconn 10000

backend web_servers
    maxconn 5000

server web1 10.0.0.10:80 maxconn 1000

3. Enable Queue Limits

backend web_servers
    timeout queue 30s

Alert on queue depth > 0 - indicates backend saturation.

4. Monitor Response Times

backend web_servers
    timeout server 30s

Track response_time_avg and alert on increases.

5. Use Stick Tables for Rate Limiting

frontend http
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src
    http-request deny if { sc_http_req_rate(0) gt 100 }

6. Enable Logging

global
    log /dev/log local0
    log /dev/log local1 notice

frontend http
    option httplog

HAProxy Performance Tuning

Connection Tuning

global
    maxconn 100000
    tune.maxaccept 1000

defaults
    timeout connect 5s
    timeout client 30s
    timeout server 30s

Buffer Tuning

global
    tune.bufsize 32768
    tune.maxrewrite 8192

Thread Configuration (HAProxy 2.0+)

global
    nbthread 4  # Number of threads = number of CPU cores

Advanced Configuration

Multiple HAProxy Instances

plugins:
  haproxy_lb1:
    enabled: true
    socket_path: /run/haproxy/lb1.sock

  haproxy_lb2:
    enabled: true
    socket_path: /run/haproxy/lb2.sock

HTTP Stats (Alternative to Socket)

plugins:
  haproxy:
    enabled: true
    stats_url: http://localhost:8404/stats;csv
    username: admin
    password: ${HAPROXY_PASSWORD}

Docker Container

Monitor HAProxy in Docker:

plugins:
  haproxy:
    enabled: true
    socket_path: /var/run/haproxy/admin.sock

Docker run with socket mount:

docker run -d --name haproxy \
  -v /var/run/haproxy:/var/run/haproxy \
  haproxy:latest

Example Configurations

Basic Production

plugins:
  haproxy:
    enabled: true
    socket_path: /run/haproxy/admin.sock

With HTTP Stats

plugins:
  haproxy:
    enabled: true
    stats_url: http://127.0.0.1:8404/stats;csv
    username: admin
    password: ${HAPROXY_ADMIN_PASSWORD}

HA Cluster

plugins:
  haproxy_master:
    enabled: true
    socket_path: /run/haproxy/master.sock

  haproxy_backup:
    enabled: true
    socket_path: /run/haproxy/backup.sock

Limitations

Current Limitations

1. No per-URL metrics - Only aggregate statistics
2. No stick table metrics - Rate limiting tables not monitored
3. No ACL metrics - ACL statistics not collected

Scalability

Tested with:

• 100,000+ concurrent connections
• 10,000+ req/sec
• 100+ backends

Performance:

• Stats socket overhead constant regardless of load

Monitoring Checklist

Critical:

1. Server DOWN
2. Backend queue > 0
3. Connection errors > 0
4. Sessions at limit

Important: 5. Health check failures 6. Response errors 7. High retry rate 8. Response time increasing

Alert Thresholds

server_status: == DOWN
backend_queue_current: > 0
backend_errors_conn_rate: > 0.01
frontend_sessions_percent: > 90
response_time_avg: > 1000

Next Steps

• View all plugins
• Nginx Plugin - Web server alternative
• Varnish Plugin - Cache layer
• System Requirements