> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Neo4j

> Neo4j transaction, query, page cache, checkpoint, Bolt connection, and JVM metrics, scraped from the server's Prometheus endpoint.

The Neo4j integration requires CXDOT Collector 1.10.0 or greater.

[Neo4j](https://neo4j.com/) is a graph database that stores data as nodes and the
relationships between them. Use the Neo4j integration to collect transaction, query,
cache, checkpoint, Bolt connection, and Java Virtual Machine (JVM) metrics from Neo4j
servers running in your environment.

The Neo4j integration supports Neo4j 5.26 or greater.

## Supported telemetry types

The Neo4j integration supports these telemetry types:

| Type | Supported |
| :-: | :-: |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## Known limitations

The Neo4j integration doesn't yet collect cluster (Raft) metrics, such as leadership,
the commit and applied indexes, and replication attempts and failures. In a clustered
deployment, each server still reports its own server-wide and per-database metrics.

## Prerequisites

The Neo4j integration has the following prerequisites:

* Run Neo4j Enterprise Edition, which exposes the metrics endpoint. To verify the
  edition, run the following query in Cypher Shell and confirm that `edition` reports
  `enterprise`:

  ```cypher theme={null}
  CALL dbms.components() YIELD name, versions, edition;
  ```

* Enable the Neo4j Prometheus endpoint and bind it to an address that the CXDOT
  Collector can reach. Neo4j disables the endpoint by default and binds it to
  `localhost:2004`. For example, add the following settings to `neo4j.conf`:

  ```properties theme={null}
  server.metrics.prometheus.enabled=true
  server.metrics.prometheus.endpoint=0.0.0.0:2004
  ```

  For the Neo4j Docker image, set
  `NEO4J_server_metrics_prometheus_enabled=true` and
  `NEO4J_server_metrics_prometheus_endpoint=0.0.0.0:2004`.

* Restrict access to the metrics endpoint. The endpoint doesn't support encryption
  or authentication and must not be exposed to the internet. For more information,
  see [Expose metrics](https://neo4j.com/docs/operations-manual/current/monitoring/metrics/expose/)
  in the Neo4j documentation.

* Select the metrics that Neo4j exposes with `server.metrics.filter`. The default
  filter omits some supported metrics, including page cache eviction and Bolt
  response metrics. To make all supported metrics available, add the following
  setting to `neo4j.conf`:

  ```properties theme={null}
  server.metrics.filter=*
  ```

The integration reads the metrics endpoint without connecting to a database or
running queries. It doesn't require Neo4j credentials.

## Configure

The Neo4j integration is enabled by default. To configure the integration, follow
these steps:

1. Add Neo4j autodiscovery annotations to pods or Services and provide the URL of
   each metrics endpoint. One elected replica of the cluster-tier
   CXDOT Collector scrapes each annotated Service. For more information, see
   [autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes)
   and
   [architecture](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/architecture).

   Metrics from discovered pods arrive with that pod's Kubernetes metadata attached.

   A discovered target takes its settings from its annotations, not from the
   integration's configuration. For example, a `neo4j_dbs` list in the annotations
   limits per-database metrics to the databases that it names. The `rename_labels`
   and `exclude_labels` settings in an annotation don't apply.

   For a Service backed by multiple Neo4j servers, use endpoint-level autodiscovery
   annotations. A Service-level target collects from the Service cluster IP and can
   mix metrics from different servers.

2. Optional: Configure static targets instead of discovered targets, such as Neo4j
   servers outside your Kubernetes cluster. For example, add the following to the
   Helm values file for your CXDOT Collector:

   ```yaml theme={null}
   config:
     integrations:
       neo4j:
         endpoints:
           - endpoint: neo4j-0.example.com:2004
           - endpoint: http://neo4j-1.example.com:2004/metrics
   ```

   A nonempty `endpoints` list disables autodiscovery for that integration instance.
   The CXDOT Collector collects from only the listed targets. In a Kubernetes
   deployment, one elected replica of the cluster-tier CXDOT Collector monitors
   static targets. List each server's address instead of a load-balanced address to
   preserve per-server metrics. The integration's `collection_interval` and `timeout`
   settings apply only to listed endpoints.

3. Optional: Configure separate integration instances to collect from discovered
   and static targets at the same time. For example:

   ```yaml theme={null}
   config:
     integrations:
       neo4j: {}
       neo4j/external:
         endpoints:
           - endpoint: neo4j-0.example.com:2004
   ```

   The bare `neo4j` key continues to use autodiscovery. The `neo4j/external` key
   defines a named instance for static targets. Keep the bare `neo4j` key: after you
   configure any Neo4j instance, the CXDOT Collector runs only the instances that you
   configure.

4. Optional: Disable the integration. For example, add the following to the Helm
   values file for your CXDOT Collector:

   ```yaml theme={null}
   config:
     integrations:
       neo4j:
         enabled: false
   ```

### Validate

To validate the Neo4j integration, follow these steps:

1. In the
   [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer),
   add the following filters:

   * `__name__=cxdot.integration.target.health`
   * `cxdot.integration.name=neo4j`

   Confirm that each target reports `1`. A value of `0` means the CXDOT Collector
   hit an error collecting from that target. The `cxdot.integration.target`
   attribute identifies each endpoint.

2. In
   [Metrics Explorer](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer),
   run the following query while your applications run transactions against Neo4j:

   ```text theme={null}
   sum by ("server.address", "server.port", "db.namespace") (rate({"neo4j.transaction.committed", "cxdot.integration.name"="neo4j"}[$__rate_interval]))
   ```

   Confirm that the query returns a value greater than `0` for each active database.
   The `server.address`, `server.port`, and `db.namespace` attributes identify the
   server and database.

### Troubleshooting

* `cxdot.integration.target.health` reports `0`: Confirm that the metrics endpoint is
  enabled, bound to an address the CXDOT Collector can reach, and accessible through
  your network policy or firewall.
* `neo4j.node.count`, `neo4j.relationship.count`, and
  `neo4j.relationship_type.count` are missing: Neo4j releases earlier than 2025.03
  leave these counts out of the default metrics filter. Add `*neo4j.count*` to
  `server.metrics.filter`. This setting replaces the default filter, so retain any
  default patterns that you need.
* A query filtered by database returns no results: Replace periods and hyphens in the
  database name with underscores. For example, Neo4j reports `sales-eu.prod` as
  `sales_eu_prod` in `db.namespace`.
* Raft metrics are missing from a clustered deployment: The integration doesn't yet
  collect them, as the Known limitations section describes.
* `jvm.gc.collection.count`, `jvm.gc.collection.time`, and the heap pools of
  `jvm.memory.used` are missing: The integration collects these metrics only from
  servers that use the G1 garbage collector.

## Configuration reference

Configure one Neo4j integration instance with the following settings. In Helm values, place
these settings under `config.integrations.neo4j`. In a Collector configuration file, place them
under `cxdot.integrations.neo4j`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this Neo4j integration instance. If true, the Collector runs the instance.
  If false, the Collector doesn't run it.

* **`endpoints`**
  Type: `array of object`. Optional. Default: `[]`.
  Neo4j Prometheus metrics endpoints to collect from. When this list is empty or omitted, the
  integration uses autodiscovery. When the list contains endpoints, this integration instance
  collects from exactly those endpoints and doesn't use autodiscovery. Configure a second, named
  instance to use both methods. Give each endpoint as `host:port` or as a full HTTP or HTTPS
  URL. The server exposes the endpoint only when `server.metrics.prometheus.enabled` is `true`,
  at the address set by `server.metrics.prometheus.endpoint`.

* **`endpoints[].endpoint`**
  Type: `string`. Required.
  Neo4j metrics endpoint as either `host:port` or a full HTTP or HTTPS URL. For `host:port`, the
  Collector requests `http://<host>:<port>/metrics`. For a full URL, the Collector requests the
  URL as written, or its `/metrics` path when the URL has no path.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `15s`.
  How often the Collector collects metrics from each endpoint in `endpoints`.

* **`timeout`**
  Type: `duration`. Optional. Default: `10s`.
  Maximum time the Collector waits for one collection from an endpoint in `endpoints`. The value
  must be greater than zero. A value longer than `collection_interval` is lowered to
  `collection_interval`.


## Related topics

- [CXDOT Collector integrations](/ingest/xcor/integrations/collector.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.