tutorial

Monitoring Cube.js with Vigilmon

Cube is your open-source semantic layer and headless BI platform — but a silent pre-aggregation failure or stale data model can break every dashboard downstream. Here's how to monitor Cube's REST API, metadata endpoint, query health, and pre-aggregation jobs with Vigilmon.

Cube (formerly Cube.js) sits between your data warehouse and your analytics applications — it handles caching, pre-aggregations, and query routing so your dashboards stay fast. When Cube goes down or its pre-aggregation workers stall, every downstream chart silently breaks or serves stale data. Vigilmon lets you monitor Cube's REST API health, data model availability, query execution, SSL certificates, and pre-aggregation refresh jobs — catching failures before your users notice blank charts.

What You'll Set Up

  • HTTP uptime monitor for Cube's REST API alive endpoint
  • Data model availability check via the /cubejs-api/v1/meta endpoint
  • Query execution health check via /cubejs-api/v1/load
  • SSL certificate expiry alerts for HTTPS Cube deployments
  • Cron heartbeat for Cube pre-aggregation refresh workers

Prerequisites

  • Cube running (self-hosted Docker or Node.js, version 0.30+)
  • Cube REST API accessible over HTTP/HTTPS
  • A Cube API secret for authenticated endpoint checks
  • A free Vigilmon account

Step 1: Monitor the Cube REST API Alive Endpoint

Cube ships a dedicated health check endpoint at /cubejs-api/v1/alive that returns 200 OK when the server is ready to handle queries. This is your primary uptime signal.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the alive endpoint URL: https://your-cube-host/cubejs-api/v1/alive
  4. Set Check interval to 2 minutes.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, add "status":"ok" to verify the response body confirms readiness.
  7. Click Save.

The /cubejs-api/v1/alive endpoint does not require authentication, making it safe to use with Vigilmon's public probing infrastructure without exposing credentials.

Step 2: Monitor the Data Model via the Meta Endpoint

The /cubejs-api/v1/meta endpoint returns your Cube data model — dimensions, measures, and cube definitions. If this endpoint fails, it typically means Cube failed to compile your schema files, a data source connection dropped, or the Cube process is partially degraded.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the meta endpoint URL: https://your-cube-host/cubejs-api/v1/meta
  3. Set Check interval to 5 minutes.
  4. Set Expected HTTP status to 200.
  5. Under Request headers, add: 
    Authorization: Bearer YOUR_CUBE_API_TOKEN
  6. Under Keyword check, add "cubes" to verify the data model JSON is present in the response.
  7. Click Save.

Generate a Cube API token for monitoring. In your Cube configuration:

// cube.js
module.exports = {
  apiSecret: process.env.CUBEJS_API_SECRET,
};

Generate a long-lived monitoring token:

# Generate a JWT for Vigilmon's monitoring user
node -e "
const jwt = require('jsonwebtoken');
const token = jwt.sign(
  { iss: 'vigilmon-monitor' },
  process.env.CUBEJS_API_SECRET,
  { expiresIn: '365d' }
);
console.log(token);
"

Store this token as a Vigilmon monitor header. If the meta endpoint returns 200 but "cubes":[], add a keyword check for a specific cube name from your data model to catch empty-model failures.

Step 3: Query Execution Health Check via the Load Endpoint

A healthy Cube server that can't execute queries is still broken. Monitor the /cubejs-api/v1/load endpoint with a simple dimension-only query against a low-cardinality cube to verify end-to-end query execution.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set Method to POST.
  3. Enter the load URL: https://your-cube-host/cubejs-api/v1/load
  4. Set Check interval to 5 minutes.
  5. Under Request headers, add: 
    Authorization: Bearer YOUR_CUBE_API_TOKEN
Content-Type: application/json
  6. Under Request body, enter a minimal query against a dimension that always returns data: 
    {
  "query": {
    "dimensions": ["Orders.status"],
    "limit": 1
  }
}
  7. Set Expected HTTP status to 200.
  8. Under Keyword check, add "data" to confirm the query returned a result set.
  9. Click Save.

Replace Orders.status with a dimension from your actual data model. Choose a cube backed by a small lookup table or a pre-aggregation so the probe query completes quickly (under 5 seconds) and doesn't trigger full warehouse scans on every check.

Step 4: SSL Certificate Alerts for HTTPS Cube Deployments

Cube deployments fronted by nginx, Caddy, or a cloud load balancer are typically served over HTTPS. Certificate expiry breaks all downstream analytics applications simultaneously.

  1. Open the Cube alive endpoint monitor 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 Cube deployments behind a reverse proxy, also add SSL monitoring on the proxy domain separately if the Cube process itself doesn't handle TLS:

# nginx config for Cube — add to your server block
server {
    listen 443 ssl;
    server_name cube.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/cube.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cube.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:4000;
        proxy_set_header Host $host;
    }
}

Add a dedicated SSL monitor for https://cube.yourdomain.com even if the underlying Cube process runs on HTTP internally.

Step 5: Heartbeat Monitoring for Pre-Aggregation Refresh Jobs

Cube's pre-aggregations are the key to fast query performance — they pre-compute rollups and cache them in your warehouse or Redis. If the refresh worker stalls, queries slow down or start failing. Use Vigilmon's cron heartbeat to verify the refresh scheduler is completing its cycles.

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to match your refreshKey schedule (e.g., 60 minutes for hourly pre-aggregations).
  3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Cube 0.31+ exposes a pre-aggregations job status API. Create a small monitoring script that checks job completion and pings the heartbeat:

// check-preaggs.js — run via cron
const axios = require('axios');

const CUBE_URL = process.env.CUBE_URL || 'http://localhost:4000';
const CUBE_TOKEN = process.env.CUBE_API_TOKEN;
const HEARTBEAT_URL = process.env.VIGILMON_HEARTBEAT_URL;

async function checkPreAggregations() {
  const response = await axios.get(
    `${CUBE_URL}/cubejs-api/v1/pre-aggregations/jobs`,
    { headers: { Authorization: `Bearer ${CUBE_TOKEN}` } }
  );

  const jobs = response.data.jobs || [];
  const failed = jobs.filter(j => j.status === 'failure');

  if (failed.length > 0) {
    console.error('Pre-aggregation failures:', failed.map(j => j.preAggregationId));
    process.exit(1);
  }

  // Ping heartbeat — all jobs healthy
  await axios.get(HEARTBEAT_URL, { timeout: 5000 });
  console.log(`Heartbeat sent — ${jobs.length} pre-aggregation jobs checked`);
}

checkPreAggregations().catch(err => {
  console.error('Check failed:', err.message);
  process.exit(1);
});

Schedule this script to run after each expected refresh cycle:

# crontab -e
# Run 5 minutes after each hour to verify hourly pre-agg refresh completed
5 * * * * CUBE_URL=http://localhost:4000 CUBE_API_TOKEN=xxx VIGILMON_HEARTBEAT_URL=https://vigilmon.online/heartbeat/abc123 node /opt/cube/check-preaggs.js

If the Cube refresh worker crashes, deadlocks on a warehouse query, or is skipped due to a configuration error, the heartbeat is never sent and Vigilmon alerts your team.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook pointing to your data engineering channel.
  2. For the alive endpoint monitor, set Consecutive failures before alert to 2 — Cube may take a moment to restart after a deployment.
  3. For the meta and load endpoint monitors, set Consecutive failures before alert to 1 — data model failures and query failures need immediate attention.
  4. For the heartbeat monitor, leave the threshold at 1 missed ping.

Cube failures cascade downstream: a broken pre-aggregation means slow queries for every dashboard user. Route Vigilmon alerts to the same channel your data engineering team monitors so the on-call engineer gets paged immediately.

Summary

| Monitor | Target | What It Catches | |---|---|---| | REST API alive | /cubejs-api/v1/alive | Server down, process crash | | Data model (meta) | /cubejs-api/v1/meta | Schema compile failure, DB disconnect | | Query execution | /cubejs-api/v1/load | Query engine failure, warehouse timeout | | SSL certificate | Cube domain | Certificate expiry | | Pre-agg heartbeat | Heartbeat URL | Refresh worker stall, missed cycle |

Cube is the query engine that keeps your analytics applications fast and consistent — but only while it's running and refreshing. With Vigilmon monitoring the alive endpoint, data model, query execution, and pre-aggregation refresh jobs, you catch Cube failures the moment they happen, long before downstream dashboards start showing blank charts or stale numbers to your users.

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