tutorial

How to Monitor QuestDB with Vigilmon (REST API, InfluxDB Line Protocol + Web Console)

QuestDB is a high-performance time-series database built for financial data, IoT telemetry, and observability pipelines — delivering SQL query performance on...

QuestDB is a high-performance time-series database built for financial data, IoT telemetry, and observability pipelines — delivering SQL query performance on time-series data with microsecond ingestion latency. It exposes multiple ingestion interfaces (HTTP REST, InfluxDB line protocol over TCP, and PostgreSQL wire protocol) and a built-in web console. Each interface is a potential failure point, and a silent failure on any one of them can mean missed sensor readings, lost trade data, or gaps in your observability pipeline.

In this tutorial you'll set up comprehensive external monitoring for QuestDB using Vigilmon, covering all four interfaces and alert configuration for your time-series data infrastructure.

Why QuestDB needs external monitoring

QuestDB's multi-interface architecture means it can have partial failures that internal health probes miss:

  • HTTP REST API becomes unresponsive — the REST query interface hangs under heavy write load; existing TCP ingestion continues but no SQL queries can execute
  • InfluxDB line protocol ingestion silently drops data — the TCP endpoint (port 9009) accepts connections but the write buffer is full; ingest clients see no error but data never appears in tables
  • PostgreSQL wire port (8812) stops accepting connections — BI tools and analytics clients that connect via the PostgreSQL protocol lose access without the HTTP interface being affected
  • Web console fails to load — the built-in web UI at port 9000 becomes unreachable; developers lose access to their primary query interface and must fall back to CLI tools
  • Disk full pauses all writes — QuestDB stops accepting new data when the underlying disk fills; the HTTP API returns 500 errors while TCP ingest silently stalls
  • JVM heap exhaustion — a query triggers excessive memory allocation; the JVM runs GC continuously, making all interfaces extremely slow without crashing outright

External monitoring from Vigilmon catches these across all interfaces — the same way your data producers and consumers experience them.

What you'll need

  • QuestDB running (self-hosted via Docker, Kubernetes, or binary)
  • HTTP REST API port accessible (default: 9000)
  • InfluxDB line protocol TCP port accessible (default: 9009)
  • PostgreSQL wire port accessible (default: 8812)
  • A free Vigilmon account — no credit card required

Step 1: Verify QuestDB endpoints are reachable

Before adding monitors, confirm all interfaces are responding.

HTTP REST API (port 9000):

QuestDB exposes a /health endpoint on port 9000:

curl http://your-questdb-host:9000/health
# {"status":"healthy"}

You can also run SQL queries via GET request — useful for validating that the query engine is actually processing requests, not just the HTTP listener:

curl "http://your-questdb-host:9000/exec?query=SELECT+1"
# {"query":"SELECT 1","columns":[{"name":"1","type":"INT"}],"timestamp":-1,"dataset":[[1]],"count":1}

InfluxDB line protocol (port 9009):

nc -zv your-questdb-host 9009
# Connection to your-questdb-host 9009 port [tcp/*] succeeded!

PostgreSQL wire protocol (port 8812):

nc -zv your-questdb-host 8812
# Connection to your-questdb-host 8812 port [tcp/*] succeeded!

Web console (port 9000, path /):

curl -I http://your-questdb-host:9000/
# HTTP/1.1 200 OK
# Content-Type: text/html

Step 2: Monitor the HTTP REST API health endpoint

The /health endpoint is QuestDB's canonical health check. It validates that the HTTP server is running and the query engine is responsive.

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

This is your primary QuestDB monitor. If the HTTP API is unreachable, both REST ingest and SQL query clients are affected.

Step 3: Monitor the query engine with a live SQL check

Beyond confirming the HTTP server is running, validate that QuestDB's query engine is actually processing requests. A simple SELECT 1 tests the full execution path without touching any real data.

In Vigilmon:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to http://your-questdb-host:9000/exec?query=SELECT+1
  4. Set expected status code: 200
  5. Under Response body contains, add "dataset":[[1]] to confirm the query returned the correct result
  6. Save the monitor

If this monitor fails while /health passes, the HTTP server is alive but the query engine has become unresponsive — a condition that can occur during excessive GC pressure or after a failed table import.

Step 4: TCP port checks for InfluxDB line protocol

The InfluxDB line protocol endpoint on port 9009 is often the primary ingest path for IoT sensors, metrics agents, and telemetry pipelines. A TCP check confirms the listener is active.

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

For a more thorough check, send an actual data point using the line protocol format and verify it appears in a table. You can do this from a separate script that pings Vigilmon's heartbeat URL after a successful write:

#!/bin/bash
# Write a test metric to QuestDB
echo "monitoring,host=probe value=1 $(date +%s%N)" | \
  nc -q 1 your-questdb-host 9009

# Query back the written value
RESULT=$(curl -s "http://your-questdb-host:9000/exec?query=SELECT+count()+FROM+monitoring+WHERE+host%3D%27probe%27")

# If the count increased, ping Vigilmon heartbeat
if echo "$RESULT" | grep -q '"count":'; then
  curl -s "https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_TOKEN"
fi

Run this script as a cron job every 5 minutes for end-to-end ingest validation.

Step 5: Monitor the PostgreSQL wire port

Analytics tools like Grafana, DBeaver, and BI platforms connect to QuestDB via its PostgreSQL-compatible wire protocol on port 8812. Monitoring this port ensures your analytics and visualization layer stays connected.

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

If port 8812 becomes unreachable while port 9000 remains up, QuestDB's PostgreSQL compatibility layer has failed — possibly due to a configuration error after an upgrade, or because a security group / firewall rule change blocked the port.

Step 6: Monitor the web console

QuestDB's built-in web console at port 9000 (root path) is the primary interface for developers to run ad-hoc queries, monitor table stats, and import/export data. Losing access to it during an incident makes debugging significantly harder.

The web console is served from the same port as the REST API. An HTTP monitor on http://your-questdb-host:9000/ with expected status 200 and response body containing QuestDB covers this:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to http://your-questdb-host:9000/
  4. Set expected status code: 200
  5. Under Response body contains, add QuestDB
  6. Save the monitor

This is a secondary monitor — if /health is down, this will be down too — but it specifically validates that the web assets are being served correctly, which can fail independently after a partial upgrade.

Step 7: Configure time-series data alerts

Data gaps in time-series pipelines can be subtle and expensive: missing sensor readings in IoT pipelines, gaps in financial tick data, or holes in observability metrics that make incident correlation impossible.

Alert channel setup

  1. In Vigilmon, go to Alert Channels → Add Channel → Email
  2. Enter your data engineering on-call address
  3. Assign to all QuestDB monitors

For webhook integration:

{
  "monitor_name": "QuestDB REST API /health",
  "status": "down",
  "url": "http://your-questdb-host:9000/health",
  "started_at": "2024-01-15T10:23:00Z",
  "duration_seconds": 60
}

Route this to PagerDuty or Opsgenie with a note in the runbook: "QuestDB outage = data gap forming. Check ingest pipeline first, then disk space."

Alert thresholds

For time-series databases, consider tighter-than-default alert thresholds:

  • Confirm immediately (0 confirmation delays): the first failed check triggers an alert — a 1-minute gap in financial or IoT data is already significant
  • Recovery alert: ensure you're notified when QuestDB comes back up, so you can verify whether ingest clients reconnected or need to be restarted

Correlating alerts with QuestDB diagnostics

When a Vigilmon alert fires:

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

# 2. Check disk usage (common cause of write failures)
df -h /var/lib/questdb/

# 3. Check JVM heap via the metrics endpoint
curl http://your-questdb-host:9000/metrics | grep jvm_memory

# 4. Test query engine responsiveness
time curl "http://your-questdb-host:9000/exec?query=SELECT+1"

# 5. Check active connections
curl "http://your-questdb-host:9000/exec?query=SELECT+*+FROM+sys.query_activity()"

If disk is the issue, QuestDB will log No space left on device errors. If JVM heap is the issue, you'll see GC overhead messages. Both require immediate action to prevent data loss.

Kubernetes deployment with monitoring-ready ports

apiVersion: v1
kind: Service
metadata:
  name: questdb
  namespace: timeseries
spec:
  type: LoadBalancer
  selector:
    app: questdb
  ports:
    - name: http
      port: 9000
      targetPort: 9000
    - name: ilp
      port: 9009
      targetPort: 9009
      protocol: TCP
    - name: pg
      port: 8812
      targetPort: 8812
      protocol: TCP

With all three ports exposed via a LoadBalancer, you can add all Vigilmon monitors pointing at the same external IP.

Recommended monitor set for QuestDB

| Monitor | Type | What it catches | |---------|------|-----------------| | http://questdb:9000/health | HTTP | HTTP server down, QuestDB process crashed | | http://questdb:9000/exec?query=SELECT+1 | HTTP | Query engine unresponsive (disk, GC, table corruption) | | questdb:9009 | TCP | InfluxDB line protocol ingest port closed | | questdb:8812 | TCP | PostgreSQL wire port unreachable, BI tools disconnected | | http://questdb:9000/ | HTTP | Web console unavailable, asset serving broken |

What's next

  • Heartbeat monitoring — for scheduled data imports or ETL jobs that write to QuestDB on a cron schedule, add Vigilmon heartbeat monitors to alert when a pipeline job stops completing
  • SSL certificate monitoring — if you front QuestDB with Nginx or Caddy for TLS termination, Vigilmon will alert you before the certificate expires
  • Status page for data consumers — create a Vigilmon status page exposing QuestDB health to data consumers and analytics teams so they know immediately when query performance degradation or outage is a database issue rather than an application issue

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

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles