How to Monitor SonarQube with Vigilmon (HTTP, Heartbeat, and SSL Alerts)

SonarQube is the leading open-source platform for static code analysis and continuous code quality inspection. Teams rely on it to catch bugs, security vulnerabilities, and code smells before they reach production — but SonarQube itself is a service that can go down, run out of memory, or stall mid-analysis. When that happens, your quality gate stops enforcing standards silently.

In this tutorial you'll set up end-to-end monitoring for SonarQube using Vigilmon — free tier, no credit card.

Why SonarQube needs dedicated monitoring

SonarQube fails in ways that aren't obvious until a developer tries to push code:

• Analysis queue stalls — the Elasticsearch cluster or compute engine backs up, analyses stop completing, and the SonarQube web UI stays green while CI pipelines hang waiting for quality gate results
• Memory exhaustion — SonarQube is Java-heavy; a full heap causes the web server to return 503s while the process stays technically alive
• Elasticsearch split-brain — the bundled Elasticsearch node loses its index, causing the UI to partially load but search and project lists to return errors
• Silent background worker death — the Compute Engine worker process can die independently of the web server, stopping new analyses while the UI reports no issues

External monitoring that checks SonarQube's health API and web availability catches all of these before your team notices.

What you'll need

• A running SonarQube instance (Community Edition or higher)
• Network access from Vigilmon to your SonarQube host (public URL or a Vigilmon agent for private networks)
• A free Vigilmon account (sign up takes 30 seconds)

Step 1: Verify SonarQube health endpoints

SonarQube exposes two built-in health endpoints you'll use as monitoring targets.

System health (requires authentication in most configurations):

GET https://sonarqube.example.com/api/system/health

Response when healthy:

{
  "health": "GREEN",
  "causes": []
}

The health field returns GREEN, YELLOW, or RED. YELLOW means SonarQube is running but degraded (e.g., a non-critical component is slow). RED means the system is not operational.

System status (often accessible without auth):

GET https://sonarqube.example.com/api/system/status

Response:

{
  "id": "...",
  "version": "10.4.0.87286",
  "status": "UP"
}

The status field returns STARTING, UP, RESTARTING, DB_MIGRATION_NEEDED, DB_MIGRATION_RUNNING, or DOWN.

Test both from your terminal:

curl -u admin:your-password https://sonarqube.example.com/api/system/health
curl https://sonarqube.example.com/api/system/status

If the /api/system/health endpoint requires authentication, note your credentials — you'll use Vigilmon's basic-auth header option in Step 2.

Step 2: Set up HTTP monitoring for the health endpoint

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS as the type
3. Set the URL to your health endpoint: https://sonarqube.example.com/api/system/health
4. Set the check interval to 1 minute
5. Under Expected response:
   • Status code: 200
   • Response body contains: "health":"GREEN"
6. If authentication is required, add an Authorization header: Basic <base64(user:password)> — or use Vigilmon's built-in basic-auth fields
7. Save the monitor

Vigilmon will now probe the health API every minute. If SonarQube returns YELLOW or RED, or if the endpoint becomes unreachable, an incident fires.

Step 3: Monitor the web UI availability

The health API and the web interface are served by the same process but can disagree during startup or partial failure. Add a second monitor for the root UI:

1. Monitors → New Monitor → HTTP / HTTPS
2. URL: https://sonarqube.example.com
3. Expected status code: 200
4. Response body contains: SonarQube (matches the page title)
5. Save the monitor

This monitor catches situations where the API responds but the web server itself returns an error page to browsers.

Step 4: Add TCP port monitoring

If SonarQube is not publicly accessible, or you want low-level reachability checks independent of the HTTP layer, set up a TCP port monitor:

1. Monitors → New Monitor → TCP Port
2. Hostname: sonarqube.example.com
3. Port: 9000 (SonarQube's default HTTP port; adjust if you run it behind a reverse proxy)
4. Save the monitor

A TCP failure means the process has crashed or the port binding has been lost — more fundamental than an HTTP check.

Step 5: Set up heartbeat monitoring for scheduled analyses

If your team runs nightly full-project analyses or other scheduled SonarQube tasks (cron-triggered scanners, CI batch jobs), configure a heartbeat monitor so Vigilmon alerts you when the job stops running.

How heartbeat monitoring works: Vigilmon gives you a unique ping URL. Your scheduled job hits that URL at the end of each successful run. If the ping doesn't arrive within the expected window, Vigilmon fires an alert.

1. In Vigilmon, go to Monitors → New Monitor → Heartbeat
2. Name it something like SonarQube nightly scan
3. Set the expected interval (e.g., 24 hours)
4. Set a grace period (e.g., 30 minutes) to allow for variable run times
5. Copy the unique ping URL Vigilmon gives you

Add the ping to your scanner invocation or CI pipeline:

#!/bin/bash
# Run SonarQube analysis
sonar-scanner \
  -Dsonar.projectKey=my-project \
  -Dsonar.sources=src \
  -Dsonar.host.url=https://sonarqube.example.com \
  -Dsonar.login=$SONAR_TOKEN

# Ping Vigilmon on success
if [ $? -eq 0 ]; then
  curl -s "https://vigilmon.online/ping/your-heartbeat-token" > /dev/null
fi

For a GitLab CI pipeline:

sonarqube-scan:
  stage: quality
  script:
    - sonar-scanner -Dsonar.projectKey=$CI_PROJECT_NAME
  after_script:
    - |
      if [ "$CI_JOB_STATUS" = "success" ]; then
        curl -s "https://vigilmon.online/ping/your-heartbeat-token"
      fi

Now if the nightly scan stops running — whether due to a CI runner failure, misconfigured credentials, or a stalled SonarQube Compute Engine — you'll know within your grace period.

Step 6: Enable SSL certificate monitoring

SonarQube is often deployed with a self-signed or short-lived certificate. An expired certificate breaks every CI pipeline that calls the SonarQube API.

Vigilmon automatically checks SSL certificate expiry for any HTTPS monitor. To review:

1. Open your SonarQube HTTP monitor in Vigilmon
2. Go to the SSL tab
3. Set the Alert before expiry threshold (e.g., 30 days)

Vigilmon will alert you before the certificate lapses — not after your CI starts failing with SSL_ERROR_RX_RECORD_TOO_LONG.

Summary: Vigilmon monitors for SonarQube

| Monitor | Type | What it catches | |---------|------|-----------------| | /api/system/health | HTTP | System degradation (YELLOW/RED), compute engine failure | | sonarqube.example.com | HTTP | Web UI availability, 503s from OOM | | sonarqube.example.com:9000 | TCP | Process crash, port binding loss | | Nightly scan | Heartbeat | Scheduled analysis stopped running | | SSL certificate | SSL | Certificate expiry before CI breaks |

What's next

• Status page — add your SonarQube monitors to a Vigilmon status page so your development team can self-serve during incidents
• Webhook alerts — connect Vigilmon to Slack, Microsoft Teams, or PagerDuty so the right person is notified when a quality gate goes offline
• Multi-instance monitoring — if you run separate SonarQube instances per team or environment, create a monitor group in Vigilmon to track them all in one view

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