Neo4j instance requirements

In order to be managed by NOM, a Neo4j instance must be running a Neo4j Enterprise Edition v4.4.2 or higher (including all 5.x versions).

Query log collection

Log manager is only compatible with Neo4j version 5+.

For the query log collection feature to work correctly, these configuration settings need to be set in the neo4j.conf file:

  • db.logs.query.enabled is set to INFO or VERBOSE.

  • db.logs.query.threshold is unset (is defaults to 0) or set to a reasonable value. This setting acts as the execution time lower bound for any completed query to appear in the logs. Thus, if this value is set too high, the queries you want to monitor may not get logged. Setting this value to zero logs every query.

  • db.logs.query.annotation_data_format is unset or set to CYPHER (which is the default value). Other formats result in partially or completely missing query log entries in NOM.

  • db.logs.query.annotation_data_as_json_enabled is unset or set to false (which is the default value). true results in partially or completely missing query log entries in NOM.

Finding out the location of server log configuration (server-logs.xml)

The location of server log configuration file is configured in neo4j.conf (see documentation on Operations Manual → server.logs.config configuration setting).

The currently effective location of server log configuration can be found out using the following Cypher query:

./cypher-shell "CALL dbms.listConfig() YIELD name, value WHERE name='server.logs.config' RETURN value"

Make sure that the server log configuration exists, otherwise NOM agent will not be able to add query log collection configuration to it.

Metrics collection

For the metrics collection feature to work correctly, these configuration settings need to be set in the neo4j.conf file:

For 4.4.x versions:

  • metrics.prometheus.endpoint=127.0.0.1:2004

  • metrics.prometheus.enabled=true

  • metrics.enabled=true

  • metrics.filter=*

  • metrics.jmx.enabled=true

  • metrics.namespaces.enabled=true

For 5.x versions:

  • server.metrics.prometheus.endpoint=127.0.0.1:2004

  • server.metrics.prometheus.enabled=true

  • server.metrics.enabled=true

  • server.metrics.filter=*

  • Discovery service v2 or server.metrics.jmx.enabled=true (JMX metrics)

For Neo4j versions prior to 5.23, enabling JMX metrics is a requirement. For versions 5.23 or newer, it is recommended to leave JMX metrics disabled and instead use discovery service v2.

User privileges

The agent logs on to the DBMS with the configured user to enable certain features such as viewing relationship and label types, managing privileges, and viewing configuration values. If you do not want to use the built-in admin user, a role with the minimum set of privileges required for full functionality can be created with:

This role definition can not be used for the user with which the Ops Manager server connects to the persistence database since it has insufficient privileges. This operator role should only be used for the DBMS you want to monitor with an agent.

 
CREATE ROLE `operator`;

GRANT ACCESS ON DATABASE * TO `operator`;
GRANT MATCH {*} ON GRAPH * NODE * TO `operator`;
GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `operator`;
GRANT SHOW CONSTRAINT ON DATABASE * TO `operator`;
GRANT SHOW INDEX ON DATABASE * TO `operator`;

GRANT EXECUTE PROCEDURE * ON DBMS TO `operator`;
GRANT EXECUTE ADMIN PROCEDURES ON DBMS TO `operator`;
GRANT SHOW SERVERS ON DBMS TO `operator`;

// Required for security manager:
GRANT USER MANAGEMENT ON DBMS TO `operator`;
GRANT ROLE MANAGEMENT ON DBMS TO `operator`;
GRANT PRIVILEGE MANAGEMENT ON DBMS TO `operator`;