Monitoring CloudBeaver with Vigilmon

CloudBeaver is the web-based version of the popular DBeaver desktop client — a self-hosted collaborative database administration interface with a Java backend and React frontend that connects to 80+ databases including PostgreSQL, MySQL, Oracle, SQL Server, MongoDB, Redis, and ClickHouse via JDBC and native drivers. Teams deploy CloudBeaver when they need fine-grained user role management, shared connection configurations, and browser-based database access without installing desktop clients. Vigilmon watches the CloudBeaver web UI, its GraphQL API, the status endpoint, and connection pool health so you know the moment the service or its database connections become unavailable.

What You'll Set Up

• HTTP monitor for the CloudBeaver web UI login page (port 8978)
• HTTP monitor for the GraphQL API endpoint (/api/gql)
• HTTP monitor for the CloudBeaver status API (/api/status)
• SSL certificate expiry alert for HTTPS-proxied deployments
• Heartbeat monitor for CloudBeaver connection pool health via GraphQL session query

Prerequisites

• CloudBeaver running and accessible (default port 8978, or behind a reverse proxy)
• At least one database connection configured in CloudBeaver
• A free Vigilmon account

Step 1: Monitor the CloudBeaver Web UI

The CloudBeaver web interface is served on port 8978 by default. This is your top-level availability check — if it fails, the entire CloudBeaver Java process or its serving layer is down.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your CloudBeaver URL:
   • Direct: http://yourserver:8978/dbeaver/
   • Behind reverse proxy: https://db.yourdomain.com/dbeaver/
4. Set Check interval to 1 minute.
5. Under Keyword check, enter CloudBeaver to verify the page serves the actual application and not an error page or nginx 502.
6. Set Expected HTTP status to 200.
7. Click Save.

For Docker-based deployments using the dbeaver/cloudbeaver image, this check confirms the container is up and the embedded Jetty server is responding on the mapped port.

Step 2: Monitor the GraphQL API Endpoint

CloudBeaver's frontend communicates entirely via a GraphQL API at /api/gql. Monitoring this endpoint verifies that the API layer is functional, not just the static file serving:

1. Click Add Monitor → HTTP / HTTPS.
2. Set the URL to:

   https://db.yourdomain.com/api/gql
   

3. Set Method to POST.
4. Set the Request body to a lightweight introspection query:

   {"query": "{ __typename }"}
   

5. Set the Content-Type header to application/json.
6. Under Keyword check, enter __typename to confirm a valid GraphQL response.
7. Set Expected HTTP status to 200.
8. Set Check interval to 2 minutes.
9. Click Save.

This introspection query is the lowest-cost valid GraphQL operation — it confirms the API is processing requests without touching any database connections or requiring authentication.

Step 3: Monitor the Status API

CloudBeaver exposes a /api/status endpoint that reports the server's operational state. This is purpose-built for health checks:

1. Click Add Monitor → HTTP / HTTPS.
2. Set the URL to:

   https://db.yourdomain.com/api/status
   

3. Under Keyword check, enter running or true to verify the status response indicates a healthy server.
4. Set Expected HTTP status to 200.
5. Set Check interval to 2 minutes.
6. Click Save.

The status endpoint responds with a JSON payload indicating CloudBeaver's internal state. If CloudBeaver is in a failed initialization state or has encountered a critical error, this endpoint returns a non-healthy status even if the web UI static files are still being served.

Step 4: SSL Certificate Alerts

CloudBeaver is typically deployed behind Nginx or Apache as a reverse proxy, with TLS terminated at the proxy. The certificates on that proxy must stay valid to maintain encrypted access to database credentials and query results.

1. Open the HTTP / HTTPS monitor you created in Step 1.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For CloudBeaver deployments where different subdomains are used for the UI and API, add certificate monitoring to both:

• https://db.yourdomain.com/ (web UI)
• https://db.yourdomain.com/api/gql (API — same cert, but verifying the proxy routes both)

A common failure mode is a reverse proxy configuration that serves the CloudBeaver UI from one virtual host but the /api/gql path from another, with different certificate renewal schedules. Monitoring both catches this.

Step 5: Heartbeat Monitoring for Connection Pool Health

CloudBeaver maintains persistent connection pools to configured databases. If the underlying databases restart (planned maintenance, crash, or auto-scaling event), CloudBeaver's connection pool can become stale — the UI may appear running but queries fail because the pooled connections are broken.

Use a heartbeat to verify that active database sessions are maintained:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the Expected ping interval to 10 minutes (or your desired check cadence).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Create a lightweight external script that queries the CloudBeaver GraphQL API with a sessionUser query to verify an active session exists, then pings the heartbeat:

#!/bin/bash
# CloudBeaver connection pool health check
# Requires a CloudBeaver service account token

CB_URL="https://db.yourdomain.com/api/gql"
CB_TOKEN="your-cloudbeaver-service-token"

RESPONSE=$(curl -s -X POST "$CB_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CB_TOKEN" \
  -d '{"query": "{ sessionUser { userId } }"}' \
  --max-time 15)

# Check that the response contains a valid userId (not null)
if echo "$RESPONSE" | grep -q '"userId"'; then
  curl -s --max-time 10 https://vigilmon.online/heartbeat/abc123
fi

Schedule this script with a system cron job every 10 minutes:

*/10 * * * * /opt/scripts/cloudbeaver-health.sh

If CloudBeaver's connection pool exhausts (all connections consumed by long-running queries), or if the backend databases restart and the pool fails to reconnect, the sessionUser query will fail or return null, and the heartbeat will stop — alerting you before users report query failures.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the web UI and GraphQL monitors — CloudBeaver's Java JVM occasionally pauses for garbage collection, which can cause a single probe miss.
3. Set the status API monitor to alert on 1 failure — the status endpoint is designed to indicate problems, so a single unhealthy response is meaningful.
4. Route GraphQL API alerts to the team that owns database access, separate from infrastructure alerts.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://db.yourdomain.com/dbeaver/ | CloudBeaver Java process down | | GraphQL API | /api/gql | API layer failure, request processing broken | | Status API | /api/status | CloudBeaver internal initialization failure | | SSL certificate | CloudBeaver HTTPS domain | Certificate expiry on reverse proxy | | Cron heartbeat | Heartbeat URL | Connection pool exhaustion or stale backend connections |

CloudBeaver's Java stack and persistent connection pools introduce failure modes that a simple HTTP ping won't catch. With Vigilmon watching the web UI, the GraphQL API, the status endpoint, and the connection pool health, you have full observability into whether CloudBeaver is truly functional — not just running — for the teams that depend on it for database access.