Skip to content
Last9
Book demo

Neo4j

Monitor Neo4j graph database metrics with OpenTelemetry and Last9

Use OpenTelemetry to monitor your Neo4j graph database and send telemetry data to Last9. Neo4j Enterprise exposes metrics natively via a built-in Prometheus endpoint on port 2004 — no exporter sidecar required.

Read the sample configuration for more details.

Prerequisites

  • Neo4j Enterprise Edition 5.x installed and running
  • Administrative access to neo4j.conf
  • Last9 account with integration credentials

Enable Neo4j Prometheus Metrics

The Prometheus metrics endpoint is disabled by default. Enable it in neo4j.conf:

server.metrics.prometheus.enabled=true
server.metrics.prometheus.endpoint=0.0.0.0:2004

Restart Neo4j to apply the change:

sudo systemctl restart neo4j

Verify the endpoint is reachable:

curl http://localhost:2004/metrics | head -20

Install OpenTelemetry Collector

sudo apt-get update && sudo apt-get install -y wget
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.144.0/otelcol-contrib_0.144.0_linux_amd64.deb
sudo dpkg -i otelcol-contrib_0.144.0_linux_amd64.deb

Configure OpenTelemetry Collector

  1. Create the Collector Configuration

    Create /etc/otelcol-contrib/config.yaml:

    receivers:
      prometheus:
        config:
          scrape_configs:
            - job_name: neo4j
              scrape_interval: 60s
              metrics_path: /metrics
              static_configs:
                - targets: ["localhost:2004"]
    

      hostmetrics:
        collection_interval: 60s
        scrapers:
          cpu:
            metrics:
              system.cpu.logical.count:
                enabled: true
          memory:
            metrics:
              system.memory.utilization:
                enabled: true
              system.memory.limit:
                enabled: true
          load:
          disk:
          filesystem:
            metrics:
              system.filesystem.utilization:
                enabled: true
          network:
          paging:
    

    processors:
      batch:
        timeout: 5s
        send_batch_size: 10000
        send_batch_max_size: 10000
      resourcedetection/system:
        detectors: ["system"]
        system:
          hostname_sources: ["os"]
      transform/hostmetrics:
        metric_statements:
          - context: datapoint
            statements:
              - set(attributes["host.name"], resource.attributes["host.name"])
              - set(attributes["db.system"], "neo4j")
    

    exporters:
      otlp/last9:
        endpoint: "{{ .Logs.WriteURL }}"
        headers:
          "Authorization": "{{ .Logs.AuthValue }}"
      debug:
        verbosity: detailed
    

    service:
      pipelines:
        metrics:
          receivers: [prometheus, hostmetrics]
          processors: [batch, resourcedetection/system, transform/hostmetrics]
          exporters: [otlp/last9, debug]

    Replace the endpoint and Authorization values with your actual Last9 credentials from the Integrations page.

  2. Start the Collector

    sudo systemctl daemon-reload
    sudo systemctl enable otelcol-contrib
    sudo systemctl start otelcol-contrib

Metrics Collected

Metric categoryExamples
Transactionsneo4j_database_neo4j_transaction_committed_total, neo4j_database_neo4j_transaction_rollbacks_total
Bolt connectionsneo4j_dbms_bolt_connections_opened_total, neo4j_dbms_bolt_connections_idle
Page cacheneo4j_dbms_page_cache_hits_total, neo4j_dbms_page_cache_page_faults_total, neo4j_dbms_page_cache_hit_ratio
Store sizesneo4j_database_neo4j_store_size_total, neo4j_database_neo4j_store_size_database
Query executionneo4j_database_neo4j_db_query_execution_latency_millis, neo4j_database_neo4j_db_query_execution_success_total
GC / JVMneo4j_dbms_vm_gc_time_g1_young_generation_total, neo4j_dbms_vm_heap_used, neo4j_dbms_vm_threads
SystemCPU, memory, disk, network via hostmetrics

Verification

  1. Check Collector Status

    sudo systemctl status otelcol-contrib

  2. View Collector Logs

    sudo journalctl -u otelcol-contrib -f

  3. Verify Metrics in Last9

    Log into your Last9 account and check that Neo4j metrics are being received. Look for metric names starting with neo4j_.

Troubleshooting

  • Prometheus endpoint not responding

    # Check Neo4j is running
    sudo systemctl status neo4j
    

    # Verify the metrics port is listening
    ss -tlnp | grep 2004
    

    # Check neo4j.conf changes took effect
    grep prometheus /etc/neo4j/neo4j.conf

  • Collector not scraping

    # Check for errors in collector logs
    sudo journalctl -u otelcol-contrib -n 50 --no-pager
    

    # Test the endpoint directly from the collector host
    curl http://localhost:2004/metrics | wc -l

Please get in touch with us on Discord or Email if you have any questions.