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. 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
editionreportsenterprise: -
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 toneo4j.conf:For the Neo4j Docker image, setNEO4J_server_metrics_prometheus_enabled=trueandNEO4J_server_metrics_prometheus_endpoint=0.0.0.0:2004. Neo4j 4.4 names these settings without theserver.prefix:metrics.prometheus.enabledandmetrics.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 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 toneo4j.conf:On Neo4j 4.4, the setting ismetrics.filter.
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:-
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:
The Collector replaces
${target.host}with the pod IP address and${target.port.metrics}with the container port namedmetrics, and collects from the/metricspath on that port. -
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:
A nonempty
endpointslist 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. List each server’s address instead of a load-balanced address to preserve per-server metrics. Thecollection_intervalandtimeoutsettings in your Helm values apply only to listed endpoints. For an annotated pod, set them in its CXDOT integration annotation. -
Optional: Configure separate integration instances to collect from annotated pods
and static targets at the same time. For example:
The bare
neo4jkey continues to discover pods. Theneo4j/externalkey defines a named instance for static targets. Keep the bareneo4jkey: after you configure any Neo4j instance, the CXDOT Collector runs only the instances that you configure. -
Optional: Disable the integration. For example, add the following to the Helm
values file for your CXDOT Collector:
Validate
To validate the Neo4j integration, follow these steps:-
In the
Live Telemetry Analyzer,
add the following filters:
__name__=cxdot.integration.target.healthcxdot.integration.name=neo4j
1. A value of0means the CXDOT Collector hit an error collecting from that target. Thecxdot.integration.targetattribute identifies each endpoint. -
In
Metrics Explorer,
run the following query while your applications run transactions against Neo4j:
Confirm that the query returns a value greater than
0for each active database. Theserver.address,server.port, anddb.namespaceattributes identify the server and database.
Troubleshooting
cxdot.integration.target.healthreports0: 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, andneo4j.relationship_type.countare missing: Neo4j releases earlier than 2025.03 leave these counts out of the default metrics filter. Add*neo4j.count*toserver.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.prodassales_eu_prodindb.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 ofjvm.memory.usedare 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 undercollection.cxdot.integrations.neo4j. In a Collector configuration file,
place them under cxdot.integrations.neo4j.
Optional settings
-
enabledType: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. -
endpointsType: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 ashost:portor as a full HTTP or HTTPS URL. The server exposes the endpoint only whenserver.metrics.prometheus.enabledistrue, at the address set byserver.metrics.prometheus.endpoint. -
endpoints[].endpointType:string. Required. Neo4j metrics endpoint as eitherhost:portor a full HTTP or HTTPS URL. Forhost:port, the Collector requestshttp://<host>:<port>/metrics. For a full URL, the Collector requests the URL as written, or its/metricspath when the URL has no path. -
collection_intervalType:duration. Optional. Default:15s. How often the Collector collects metrics from each endpoint inendpoints. -
timeoutType:duration. Optional. Default:10s. Maximum time the Collector waits for one collection from an endpoint inendpoints. The value must be greater than zero. A value longer thancollection_intervalis lowered tocollection_interval. -
max_samplesType:integer. Optional. Default:0. Minimum:0. Maximum number of samples accepted from one metric collection. A value of0, the default, means no limit. A collection that exceeds the limit fails and reportsupas0instead of returning an incomplete set of samples. -
follow_redirectsType: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. -
databasesType: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. -
labelsType:object. Optional. Settings that drop metric samples based on their label values. -
labels.sample_drop_rulesType: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".+".