How to Monitor FerretDB with Vigilmon (Wire Protocol + HTTP Debug + Alerts)

FerretDB is an open-source MongoDB-compatible database that translates MongoDB wire protocol queries to PostgreSQL storage. It lets you run MongoDB-compatible applications against your own Postgres backend — no licensing costs, no vendor lock-in, and full control over your data. But as a relatively new project with an active development pace, FerretDB introduces failure modes worth monitoring: the wire protocol listener can become unresponsive while PostgreSQL remains healthy, and the HTTP debug interface can signal internal errors long before clients start failing.

In this tutorial you'll set up external uptime monitoring for FerretDB using Vigilmon, covering wire protocol port checks, the HTTP debug endpoint, and alert configuration for database availability.

Why FerretDB needs external monitoring

FerretDB sits between your application and PostgreSQL, translating MongoDB wire protocol to SQL. This translation layer introduces a distinct class of failure:

• Wire protocol listener crash — the FerretDB process exits or the TCP listener stops accepting connections; your PostgreSQL backend is healthy but all application connections fail with "connection refused"
• Translation layer hang — FerretDB accepts connections but hangs on specific query patterns; new connections queue up, existing connections time out silently
• Backend PostgreSQL connectivity lost — FerretDB can't reach its PostgreSQL backend; the wire protocol port stays open but all queries return errors
• Debug endpoint signals internal panic — FerretDB's /debug/pprof/ and metrics endpoint surface goroutine panics and memory issues before they cause visible failures
• Container restart loop — a recurring OOM or panic causes FerretDB to crash-loop; Kubernetes restarts it within seconds, but connection-sensitive applications see intermittent failures that are hard to reproduce

External monitoring from Vigilmon catches these at the TCP and HTTP level — the same view your applications have — rather than relying on Kubernetes health probes which may lag several seconds behind the actual failure.

What you'll need

• FerretDB running (self-hosted via Docker, Kubernetes, or bare metal)
• MongoDB wire protocol port accessible (default: 27017)
• FerretDB HTTP debug port accessible (default: 8080)
• A free Vigilmon account — no credit card required

Step 1: Verify FerretDB is reachable

Before adding monitors, confirm FerretDB is listening on both ports.

Wire protocol port (27017):

# TCP check — should connect immediately
nc -zv your-ferretdb-host 27017
# Connection to your-ferretdb-host 27017 port [tcp/*] succeeded!

HTTP debug/metrics port (8080):

FerretDB exposes diagnostic endpoints on port 8080:

curl http://your-ferretdb-host:8080/debug/metrics
# # HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# go_gc_duration_seconds{quantile="0"} 4.25e-05
# ...

curl http://your-ferretdb-host:8080/debug/healthz
# {"status":"ok"}

The /debug/healthz endpoint is the canonical health check — it returns 200 when FerretDB is running and connected to its PostgreSQL backend.

If FerretDB is running in Kubernetes, expose both ports:

apiVersion: v1
kind: Service
metadata:
  name: ferretdb
  namespace: database
spec:
  type: LoadBalancer
  selector:
    app: ferretdb
  ports:
    - name: wire
      port: 27017
      targetPort: 27017
      protocol: TCP
    - name: http
      port: 8080
      targetPort: 8080
      protocol: TCP

Step 2: Monitor the HTTP health endpoint

FerretDB's /debug/healthz endpoint is the most reliable signal for database availability. It checks both the FerretDB process and its connection to PostgreSQL.

1. Log in at vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS
3. Set the URL to http://your-ferretdb-host:8080/debug/healthz
4. Set expected status code: 200
5. Under Response body contains, add "ok" to confirm the health response body
6. Set check interval: 1 minute
7. Save the monitor

This single check validates the entire FerretDB stack: process running, goroutines healthy, and PostgreSQL backend reachable. If any layer fails, this endpoint returns a non-200 status.

Step 3: Monitor the wire protocol port with TCP checks

The HTTP health endpoint can become unresponsive while the wire protocol port remains open (or vice versa). A TCP check on port 27017 gives you an independent signal for the MongoDB compatibility layer.

1. Go to Monitors → New Monitor
2. Choose TCP Port
3. Enter your FerretDB host and port 27017
4. Set check interval: 1 minute
5. Save the monitor

If the TCP check fails but the HTTP check passes, FerretDB's wire protocol listener has crashed while the HTTP server is still running — a state that can occur during hot restarts or when resource limits cause partial process failure.

If both checks fail simultaneously, the FerretDB process has exited entirely.

Step 4: Monitor the Prometheus metrics endpoint

FerretDB exposes Prometheus-format metrics at /debug/metrics. Beyond just confirming the process is alive, you can use Vigilmon's response body check to validate that FerretDB is actively handling connections.

curl http://your-ferretdb-host:8080/debug/metrics | grep ferretdb_requests
# ferretdb_requests_total{command="find",status="ok"} 1024
# ferretdb_requests_total{command="insert",status="ok"} 512

In Vigilmon, add an HTTP monitor for http://your-ferretdb-host:8080/debug/metrics:

• Expected status: 200
• Response body contains: ferretdb_ (confirms metrics output, not an error page)

This monitor also serves as an early warning for connection pool saturation: if the metrics endpoint becomes slow to respond, it's often a sign that FerretDB's goroutine pool is under pressure.

Step 5: Configure a connection test via FerretDB's ping endpoint

FerretDB supports MongoDB's ping command over the wire protocol. For a more complete end-to-end check that validates both the wire protocol and backend connectivity, you can use mongosh or the MongoDB driver from a monitoring host:

# Using mongosh to send a ping command
mongosh "mongodb://your-ferretdb-host:27017/" --eval "db.runCommand({ping: 1})" --quiet
# { ok: 1 }

For a lightweight alternative without the MongoDB client, use netcat to send the raw ping message and check for a valid response:

# TCP connection check (Vigilmon handles this automatically)
nc -zv your-ferretdb-host 27017

Vigilmon's TCP monitor handles this — the connection itself confirms FerretDB is accepting new connections on the wire protocol port.

Step 6: Configure database alerts

FerretDB is often the sole MongoDB-compatible endpoint for your applications. An outage immediately affects all connected apps.

Email alerts

1. In Vigilmon, go to Alert Channels → Add Channel → Email
2. Enter your DBA or backend team on-call address
3. Assign the channel to all FerretDB monitors

Webhook integration

Route alerts to your incident management system:

{
  "monitor_name": "FerretDB healthz",
  "status": "down",
  "url": "http://your-ferretdb-host:8080/debug/healthz",
  "started_at": "2024-01-15T10:23:00Z",
  "duration_seconds": 30
}

For Slack, create a #database-alerts channel and route FerretDB monitor webhooks there. A 30-second outage on a database is significant — alert immediately, don't wait for multiple failed checks.

Correlating Vigilmon alerts with FerretDB state

When a Vigilmon alert fires, triage in this order:

# 1. Check FerretDB process state
docker logs ferretdb --tail 50
# or in Kubernetes:
kubectl logs -n database -l app=ferretdb --tail 50

# 2. Check PostgreSQL connectivity from FerretDB
kubectl exec -n database -it $(kubectl get pod -n database -l app=ferretdb -o name) -- \
  wget -qO- http://localhost:8080/debug/healthz

# 3. Verify PostgreSQL is accepting connections
psql -h your-postgres-host -U ferretdb -c "SELECT 1"

# 4. Check active connections
mongosh "mongodb://your-ferretdb-host:27017/admin" --eval \
  "db.runCommand({currentOp: 1})" --quiet | head -30

If FerretDB's health endpoint returns an error mentioning PostgreSQL, the database backend is the problem. If the wire protocol is down but the HTTP endpoint is up, FerretDB's listener has failed and a process restart is needed.

Recommended monitor set for FerretDB

| Monitor | Type | What it catches | |---------|------|-----------------| | http://ferretdb:8080/debug/healthz | HTTP | Process crash, PostgreSQL backend unreachable | | ferretdb:27017 | TCP | Wire protocol listener failure | | http://ferretdb:8080/debug/metrics | HTTP | Metrics endpoint down, goroutine pool issues |

Docker Compose deployment with monitoring-ready configuration

If you're running FerretDB with Docker Compose, ensure the debug port is exposed:

version: "3.8"
services:
  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:latest
    ports:
      - "27017:27017"
      - "8080:8080"
    environment:
      FERRETDB_POSTGRESQL_URL: postgres://ferretdb:password@postgres:5432/ferretdb
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/debug/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: ferretdb
      POSTGRES_PASSWORD: password
      POSTGRES_DB: ferretdb
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

With both ports mapped, you can point Vigilmon directly at the host IP without any additional routing configuration.

What's next

• SSL/TLS monitoring — if you terminate TLS in front of FerretDB (via Nginx or HAProxy), add Vigilmon's certificate expiry monitoring to alert before the cert lapses and client connections fail
• Heartbeat monitoring — if you run database backup scripts on a schedule, use Vigilmon's heartbeat monitors to alert when a backup job stops completing
• Status page — create a Vigilmon status page for your database tier so frontend and backend teams know immediately when a database issue is causing application failures

Get started free at vigilmon.online — no credit card, monitoring starts in under a minute.