> ## 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 4.4, and 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.

On Neo4j 4.4, the integration also doesn't collect cluster catch-up and store copy
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`.

  Neo4j 4.4 names these settings without the `server.` prefix:
  `metrics.prometheus.enabled` and `metrics.prometheus.endpoint`.

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

  On Neo4j 4.4, the setting is `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. You can configure targets either by
annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm
values. To configure the integration, follow these steps:

1. To collect from Neo4j pods in Kubernetes, add a CXDOT integration annotation to the
   pod template. The annotation key must end with the container name. For example, add
   the following annotation to your Neo4j workload:

   ```yaml theme={null}
   spec:
     template:
       metadata:
         annotations:
           integrations.cxdot.paloaltonetworks.com/neo4j: |
             schema_version: v1.14
             neo4j:
               endpoints:
                 - endpoint: ${target.host}:${target.port.metrics}
       spec:
         containers:
           - name: neo4j
             image: neo4j:5.26-enterprise
             ports:
               - name: metrics
                 containerPort: 2004
   ```

   The Collector replaces `${target.host}` with the pod IP address and
   `${target.port.metrics}` with the container port named `metrics`, and collects from
   the `/metrics` path on that port.

2. Optional: To collect from Neo4j servers outside your Kubernetes cluster, configure
   static targets. For example, add the following to the
   Helm values file for your CXDOT Collector:

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

   A nonempty `endpoints` list disables discovery 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. For
   more information, see
   [architecture](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/architecture.md).
   List each server's address instead of a load-balanced address to preserve per-server
   metrics. The `collection_interval` and `timeout` settings in your Helm values apply
   only to listed endpoints. For an annotated pod, set them in its CXDOT integration
   annotation.

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

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

   The bare `neo4j` key continues to discover pods. 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}
   collection:
     cxdot:
       integrations:
         neo4j:
           enabled: false
   ```

Metrics from each discovered pod include that pod's Kubernetes metadata. For more
information, see
[autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

### Validate

To validate the Neo4j integration, follow these steps:

1. In the
   [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer.md),
   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.md),
   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 `collection.cxdot.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`.

* **`max_samples`**
  Type: `integer`. Optional. Default: `0`. Minimum: `0`.
  Maximum number of samples accepted from one metric collection. A value of `0`, the default,
  means no limit. A collection that exceeds the limit fails and reports `up` as `0` instead of
  returning an incomplete set of samples.

* **`follow_redirects`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to follow HTTP redirects. If true, the Collector follows redirects. If false, a
  redirect causes the metric collection to fail.

* **`databases`**
  Type: `array of string`. Optional. Default: `[]`.
  Databases to collect per-database metrics from. Server-wide metrics are always collected. When
  this list is empty or omitted, the Collector collects metrics for every database.

* **`labels`**
  Type: `object`. Optional.
  Settings that drop metric samples based on their label values.

* **`labels.sample_drop_rules`**
  Type: `object`. Optional. Default: `{}`.
  Drops a whole sample when one of its labels matches. Each key is a label name. The value is a
  list of regular expressions matched against the label's value. To drop every sample the label
  appears on with a non-empty value, use `".+"`.


## Related topics

- [CXDOT Collector integrations](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector.md)


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