# Neo4j

> Monitor Neo4j graph database metrics with OpenTelemetry and Last9

Source: https://last9.io/docs/integrations/databases/neo4j/

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](https://github.com/last9/opentelemetry-examples/tree/main/otel-collector/neo4j) for more details.

## Prerequisites

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

:::note
The Prometheus metrics endpoint (`server.metrics.prometheus.*`) is an Enterprise-only feature. It is not available in Neo4j Community Edition.
:::

## Enable Neo4j Prometheus Metrics

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

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

Restart Neo4j to apply the change:

```bash
sudo systemctl restart neo4j
```

Verify the endpoint is reachable:

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

## Install OpenTelemetry Collector

**AMD64**

```bash
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
```

**ARM64**

```bash
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_arm64.deb
sudo dpkg -i otelcol-contrib_0.144.0_linux_arm64.deb
```

**RPM (RHEL/CentOS)**

```bash
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.144.0/otelcol-contrib_0.144.0_linux_amd64.rpm
sudo rpm -ivh otelcol-contrib_0.144.0_linux_amd64.rpm
```

## Configure OpenTelemetry Collector

1. **Create the Collector Configuration**

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

   ```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](https://app.last9.io/integrations).

2. **Start the Collector**

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

## Metrics Collected

| Metric category  | Examples                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Transactions     | `neo4j_database_neo4j_transaction_committed_total`, `neo4j_database_neo4j_transaction_rollbacks_total`            |
| Bolt connections | `neo4j_dbms_bolt_connections_opened_total`, `neo4j_dbms_bolt_connections_idle`                                    |
| Page cache       | `neo4j_dbms_page_cache_hits_total`, `neo4j_dbms_page_cache_page_faults_total`, `neo4j_dbms_page_cache_hit_ratio`  |
| Store sizes      | `neo4j_database_neo4j_store_size_total`, `neo4j_database_neo4j_store_size_database`                               |
| Query execution  | `neo4j_database_neo4j_db_query_execution_latency_millis`, `neo4j_database_neo4j_db_query_execution_success_total` |
| GC / JVM         | `neo4j_dbms_vm_gc_time_g1_young_generation_total`, `neo4j_dbms_vm_heap_used`, `neo4j_dbms_vm_threads`             |
| System           | CPU, memory, disk, network via `hostmetrics`                                                                      |

## Verification

1. **Check Collector Status**

   ```bash
   sudo systemctl status otelcol-contrib
   ```

2. **View Collector Logs**

   ```bash
   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**

  ```bash
  # 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**

  ```bash
  # 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](https://discord.com/invite/Q3p2EEucx9) or [Email](mailto:support@last9.io) if you have any questions.