Monitoring Neo4j with Vigilmon

Neo4j powers knowledge graphs, fraud detection networks, recommendation engines, and any domain where relationships between data matter more than the data itself. Unlike SQL databases, Neo4j is built for highly-connected datasets where JOIN performance degrades — but that unique architecture means a down browser UI or unreachable transaction API has an outsized impact on every connected application. Vigilmon keeps watch over your Neo4j Browser, REST endpoints, SSL certificates, and scheduled Cypher jobs so you know before your users do when something goes wrong.

What You'll Set Up

• HTTP uptime monitor for the Neo4j Browser web UI (port 7474)
• REST availability check for the cluster/database availability endpoint
• Cypher transaction API health check (POST endpoint with RETURN 1 query)
• SSL certificate alerts for HTTPS/Bolt TLS deployments (port 7473)
• Cron heartbeat for scheduled Cypher procedures and APOC triggers

Prerequisites

• Neo4j Community or Enterprise 5.x running on a server or VM
• Neo4j Browser accessible at http://your-server:7474 (or HTTPS at port 7473)
• A free Vigilmon account

Step 1: Monitor the Neo4j Browser Web UI

The Neo4j Browser is the primary interface for running Cypher queries, inspecting the graph, and administering the database. If it goes down, developers and data engineers lose visibility entirely.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-server:7474
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Neo4j Browser loads a single-page React application, so a 200 response from port 7474 confirms the web server component is up. If your Neo4j instance is behind a reverse proxy or a load balancer, use the public hostname instead:

https://neo4j.yourdomain.com

Step 2: Monitor the Database Availability Endpoint

Neo4j exposes a dedicated REST endpoint for checking whether a specific database is available and accepting queries. This is more reliable than the browser check because it probes the database engine itself, not just the web layer.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://your-server:7474/db/neo4j/cluster/available
3. Set Expected HTTP status to 200.
4. Set Check interval to 1 minute.
5. Click Save.

This endpoint returns 200 when the neo4j database (the default) is available. For named databases in Enterprise Edition, replace neo4j with your database name:

http://your-server:7474/db/myapp/cluster/available

The endpoint returns 503 when the database is not available — Vigilmon will alert immediately when this happens.

Step 3: Monitor the Cypher Transaction API

The Cypher Transactional HTTP API is what most application drivers use under the hood when Neo4j's Bolt protocol isn't in play. Monitoring it with a real query confirms the query engine is accepting and processing work — not just responding to ping checks.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://your-server:7474/db/neo4j/tx
3. Set Method to POST.
4. Add the header: Content-Type: application/json
5. Set the request body:

{
  "statements": [
    { "statement": "RETURN 1 AS n" }
  ]
}

6. Set Expected HTTP status to 201 (Neo4j returns 201 Created for new transactions).
7. Optionally set Response body contains to "n":1 to validate the query returned the expected result.
8. Click Save.

This confirms the Cypher engine processes queries end-to-end — if the transaction API returns a 500 or times out, your applications can't write or read from the graph.

Step 4: SSL Certificate Alerts for HTTPS/Bolt TLS Deployments

Neo4j supports HTTPS for the browser and REST APIs (port 7473) and TLS for the Bolt protocol (default port 7687). PKI management is especially important here: Neo4j Community Edition ships with a self-signed certificate by default, and Enterprise Edition integrates with custom CA chains. An expired certificate breaks all encrypted connections to the database.

Add a certificate expiry monitor for the HTTPS endpoint:

1. Open the HTTP monitor created in Step 1 (or add a new HTTP / HTTPS monitor pointing to https://your-server:7473).
2. Enable Monitor SSL certificate in the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

To check what certificate Neo4j is currently serving:

echo | openssl s_client -connect your-server:7473 2>/dev/null | openssl x509 -noout -dates
# notAfter=Mar 15 00:00:00 2026 GMT

If you're using Let's Encrypt with a reverse proxy in front of Neo4j, add the SSL monitor to your proxy's public domain hostname instead — that's where the publicly trusted certificate lives.

Step 5: Heartbeat Monitoring for Scheduled Cypher Procedures

Neo4j doesn't have a native cron daemon, but scheduled work happens through several mechanisms: APOC's apoc.periodic.commit and apoc.periodic.iterate procedures, APOC triggers that fire on graph events, and GDS (Graph Data Science) algorithm scheduling for background graph projections. These jobs run silently — if one stops firing (due to a memory error, procedure removal, or database restart clearing the schedule), there's no built-in alert.

Use Vigilmon's cron heartbeat to confirm your scheduled jobs are still running.

In Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your job frequency (e.g. 60 minutes for an hourly maintenance procedure).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

In your scheduled Cypher procedure:

If you're using APOC's apoc.periodic.commit for data maintenance, add an HTTP call at the end of the procedure or wrap it in a script:

// Schedule in Neo4j using APOC (run once to register)
CALL apoc.periodic.repeat(
  'vigilmon-heartbeat',
  'CALL apoc.load.jsonParams("https://vigilmon.online/heartbeat/abc123", {}, null) YIELD value RETURN value',
  3600  // interval in seconds
)

For externally-scheduled jobs (cron scripts or application-level schedulers), add the heartbeat ping at the end of each successful run:

#!/bin/bash
# Neo4j maintenance script
cypher-shell -u neo4j -p "$NEO4J_PASSWORD" \
  "CALL apoc.maintenance.rebuildIndex('Person', 'name')" && \
curl -s https://vigilmon.online/heartbeat/abc123

If the job crashes before the curl call, Vigilmon never receives the ping and alerts after the expected interval lapses.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook endpoint.
2. On the transaction API monitor, set Consecutive failures before alert to 2 — brief Neo4j garbage collection pauses can cause single-probe timeouts that self-resolve.
3. Use Maintenance windows when running APOC schema operations or index rebuilds that temporarily slow the transaction API:

# Suppress alerts during a planned index rebuild
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 30}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | Neo4j Browser UI | http://server:7474 | Browser server crash, web layer down | | Database availability | /db/neo4j/cluster/available | Database engine unavailable, cluster failure | | Transaction API | /db/neo4j/tx POST | Cypher engine stalled, query processing failure | | SSL certificate | Port 7473 HTTPS | Certificate expiry, TLS handshake failure | | Cron heartbeat | Heartbeat URL | Scheduled procedure missed, APOC job failure |

Neo4j's graph engine is built for resilience under complex connected-data queries — but keeping the infrastructure itself visible requires active monitoring. With Vigilmon watching your browser endpoint, transaction API, SSL certificate, and scheduled procedures, you get the full operational picture without having to check Neo4j logs manually to know whether your graph is healthy.