How to Monitor MariaDB MaxScale with Vigilmon

MariaDB MaxScale is the database proxy layer that every MariaDB/MySQL high-availability stack depends on. It handles read-write splitting, connection pooling, automatic failover, and query routing — sitting between your application and your database backends. When MaxScale has a problem, all of your database connections have a problem.

In this tutorial you'll set up comprehensive monitoring for MaxScale using Vigilmon — covering the REST API, backend server states, connection pools, and failover events.

Why MaxScale monitoring matters

MaxScale failures are uniquely dangerous because they're often invisible at the application layer until it's too late:

• Silent routing failures — MaxScale is up but routing writes to a replica; your application sees no error until it reads back unexpected data
• Connection pool exhaustion — the pool fills silently; new application connections queue and then timeout with no clear database error
• Undetected primary failure — the primary is down but MaxScale hasn't completed failover; writes block for the duration of the election
• Service stopped — a MaxScale service or listener stops accepting connections while the process stays running; maxctrl list services shows it, HTTP monitoring doesn't

External monitoring against the MaxScale REST API (port 8989) is the only reliable way to catch all of these before your users do.

What you'll need

• A running MaxScale instance (single node or clustered)
• The MaxScale REST API enabled (enabled by default on port 8989)
• A free Vigilmon account

Step 1: Verify MaxScale REST API access

MaxScale exposes a REST API on port 8989 with basic HTTP authentication (default credentials admin/mariadb). Confirm it's reachable:

curl -u admin:mariadb http://your-maxscale-host:8989/v1/maxscale

You should see a JSON response with MaxScale version and uptime information. If you're using a custom admin user, substitute those credentials.

For production, restrict the REST API to your monitoring subnet in maxscale.cnf:

[MaxScale]
admin_host     = 0.0.0.0
admin_port     = 8989
admin_auth     = true
admin_ssl      = false

To enable HTTPS for the REST API (recommended), add:

admin_ssl           = true
admin_ssl_key       = /etc/maxscale/ssl/server.key
admin_ssl_cert      = /etc/maxscale/ssl/server.crt
admin_ssl_ca_cert   = /etc/maxscale/ssl/ca.crt

Step 2: Monitor the MaxScale REST API endpoint

The MaxScale REST API health probe is GET /v1/maxscale — it returns 200 as long as MaxScale is running and the admin interface is responsive.

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS as the type
3. Set the URL to http://your-maxscale-host:8989/v1/maxscale
4. Under Authentication, set Basic Auth with your MaxScale admin credentials
5. Set the check interval to 1 minute
6. Under Expected response, set status code 200
7. Optionally add a response body check for "version" to confirm you're hitting a valid MaxScale response
8. Save the monitor

If this monitor goes down, MaxScale itself is unreachable — all application database connections are broken.

Step 3: Monitor backend server health via the servers API

MaxScale tracks the state of each MariaDB/MySQL backend server. Use the /v1/servers endpoint to expose this:

curl -u admin:mariadb http://your-maxscale-host:8989/v1/servers | jq '.data[].attributes.state'

Healthy output for a primary-replica setup:

"Master, Running"
"Slave, Running"
"Slave, Running"

Unhealthy states you want to alert on:

"Down"
"Maintenance"
"Relay Master, Running"   # unexpected topology

Add an HTTP monitor in Vigilmon:

1. New Monitor → HTTP / HTTPS
2. URL: http://your-maxscale-host:8989/v1/servers
3. Basic Auth with your admin credentials
4. Under Expected response body, set: must NOT contain "Down" (use the absence check)
5. Alternatively, set up a webhook receiver script that parses the JSON and alerts on any server not in Running state

For a simpler alert that doesn't require body parsing, monitor the servers endpoint response time — a sudden latency spike here often precedes a backend going down.

Step 4: Set up TCP port monitoring for MaxScale listener ports

MaxScale services bind listener ports that your application connects to. These are separate from the REST API. Monitor them with TCP checks:

Common default MaxScale listener ports:

| Service | Default Port | Purpose | |---------|-------------|---------| | ReadWriteSplit | 4006 | Read-write splitting router | | ReadConnRoute | 4008 | Read-only connection router | | Binlog Router | 3306 | Binlog relay service | | MaxScale Admin | 8989 | REST API and web UI |

For each listener port your application uses:

1. New Monitor → TCP Port
2. Hostname: your-maxscale-host
3. Port: 4006 (or whichever your app uses)
4. Save

A TCP failure here means MaxScale's listener has stopped accepting connections — your application is completely cut off from the database.

Step 5: Monitor connection pool utilization

MaxScale's connection pool stats are available via the REST API:

curl -u admin:mariadb \
  http://your-maxscale-host:8989/v1/servers | \
  jq '.data[] | {name: .id, connections: .attributes.statistics.connections, max_connections: .attributes.parameters.max_connections}'

Set up a monitoring script that Vigilmon can hit via heartbeat:

#!/bin/bash
# /usr/local/bin/check-maxscale-pool.sh

MAXSCALE_HOST="localhost"
MAXSCALE_PORT="8989"
MAXSCALE_USER="admin"
MAXSCALE_PASS="mariadb"
THRESHOLD=90

response=$(curl -s -u "${MAXSCALE_USER}:${MAXSCALE_PASS}" \
  "http://${MAXSCALE_HOST}:${MAXSCALE_PORT}/v1/servers")

# Parse and check each server's pool utilization
echo "$response" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for server in data['data']:
    stats = server['attributes'].get('statistics', {})
    conns = stats.get('connections', 0)
    max_conns = server['attributes'].get('parameters', {}).get('max_connections', 100)
    pct = (conns / max_conns) * 100
    if pct > ${THRESHOLD}:
        print(f'ALERT: {server[\"id\"]} pool at {pct:.0f}% ({conns}/{max_conns})')
        sys.exit(1)
print('OK: all pools below ${THRESHOLD}%')
"

Run this script as a cron job and report to a Vigilmon heartbeat monitor — if the script doesn't check in, or reports an error, you'll get an alert.

Step 6: Configure alerting for MaxScale incidents

When MaxScale goes down or a backend fails, you need to know immediately:

1. Go to Alert Channels → Add Channel
2. Choose Email or Webhook (Slack, PagerDuty, Discord)
3. For a Slack webhook, Vigilmon sends:

{
  "monitor_name": "MaxScale REST API",
  "status": "down",
  "url": "http://your-maxscale-host:8989/v1/maxscale",
  "started_at": "2026-01-15T10:23:00Z",
  "duration_seconds": 30
}

4. Assign the alert channel to all your MaxScale monitors

Recommended alert policy:

• MaxScale REST API down → page immediately (P1 — all DB connections broken)
• Backend server Down → page immediately (P1 — cluster degraded, failover may be needed)
• Listener TCP down → page immediately (P1 — application cut off)
• Connection pool >90% → warn (P2 — scale the pool before it exhausts)
• Replication lag >1s → warn (P2 — stale reads possible on replicas)

Step 7: Create a status page for your database layer

A status page lets your team see database proxy health at a glance during incidents:

1. Go to Status Pages → New Status Page
2. Name it "Database Layer"
3. Add monitors:
   • MaxScale REST API (HTTP)
   • ReadWriteSplit listener TCP
   • ReadConnRoute listener TCP
   • Backend servers endpoint
4. Publish the page

During a failover event, your team can watch the status page to see MaxScale recover — the backend server states will flicker to Down and back to Running as the promotion completes.

Putting it all together

| Monitor | Type | Alert level | What it catches | |---------|------|-------------|-----------------| | http://maxscale:8989/v1/maxscale | HTTP | P1 | MaxScale process down | | maxscale:4006 | TCP | P1 | ReadWriteSplit listener stopped | | maxscale:4008 | TCP | P1 | ReadConn listener stopped | | http://maxscale:8989/v1/servers | HTTP | P1 | Backend server state (Down/Maintenance) | | Connection pool heartbeat | Heartbeat | P2 | Pool >90% utilization | | Replication lag heartbeat | Heartbeat | P2 | Replica lag >1s |

What's next

• Failover event tracking — use MaxScale's event logging (maxscale.log) and ship logs to your observability stack to track failover frequency and duration
• Query response time — MaxScale's query logging can record per-query latency; integrate with your metrics pipeline to track P95 latency at the proxy layer
• Binlog router health — if you use MaxScale as a binlog relay, add a heartbeat monitor for the binlog position advancing on schedule

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.