Neo4j

The Neo4j integration requires CXDOT Collector 1.10.0 or greater. Neo4j 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:

​

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:
  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:
  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 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:
  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 and 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:
   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:
   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:
   config:
     integrations:
       neo4j:
         enabled: false
   

​

Validate

To validate the Neo4j integration, follow these steps:

1. In the Live 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, run the following query while your applications run transactions against Neo4j:
   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.