New to KubeDB? Please start here.

Monitoring Neo4j with KubeDB

KubeDB has native support for monitoring via Prometheus. You can use builtin Prometheus scraper or Prometheus operator to monitor KubeDB-managed Neo4j clusters. This guide shows how Neo4j monitoring works with KubeDB and how to configure Neo4j CR to enable monitoring.

Overview

KubeDB uses an exporter sidecar to expose Prometheus metrics from Neo4j pods. The following diagram shows the logical monitoring flow for Neo4j with KubeDB.

When a user creates a Neo4j CR with spec.monitor configured, KubeDB provisions the database and creates a dedicated stats service named {neo4j-name}-stats for monitoring. Prometheus scrapes metrics from this stats service.

Configure Monitoring

To enable monitoring for Neo4j, configure the spec.monitor section. KubeDB provides the following options:

Sample Configuration

A sample YAML for a Neo4j cluster with monitoring enabled using Prometheus operator is shown below.

apiVersion: kubedb.com/v1alpha2
kind: Neo4j
metadata:
  name: sample-neo4j
  namespace: demo
spec:
  version: "2025.12.1"
  replicas: 3
  deletionPolicy: WipeOut
  storage:
    storageClassName: local-path
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 2Gi
  monitor:
    agent: prometheus.io/operator
    prometheus:
      serviceMonitor:
        labels:
          release: prometheus
        interval: 10s

Here, spec.monitor.agent: prometheus.io/operator tells KubeDB to create monitoring resources for Prometheus operator. KubeDB creates a ServiceMonitor object with the configured labels, and the Prometheus server discovers and scrapes Neo4j metrics through {neo4j-name}-stats service.

Next Steps

• Monitor Neo4j using Builtin Prometheus.
• Monitor Neo4j using Prometheus Operator.
• Configure alerting and dashboards from scraped metrics in Prometheus/Grafana.