Chapter 9. JMX metrics

For more monitoring options, see Neo4j Operations Manual → Monitoring. Most of the monitoring features are only available in the Enterprise edition of Neo4j.

In order to be able to continuously get an overview of the health of a Neo4j database, there are different levels of monitoring facilities available. Most of these are exposed through JMX. Neo4j Enterprise also has the ability to automatically report metrics to commonly used monitoring systems.

9.1. Adjusting remote JMX access to the Neo4j Server

Per default, the Neo4j Enterprise Server edition does not allow remote JMX connections, since the relevant options in the conf/neo4j.conf configuration file are commented out. To enable this feature, you have to remove the # characters from the various com.sun.management.jmxremote options there.

When commented in, the default values are set up to allow remote JMX connections with certain roles, refer to the conf/jmx.password, conf/jmx.access, and conf/neo4j.conf files for details.

Make sure that conf/jmx.password has the correct file permissions. The owner of the file has to be the user that will run the service, and the permissions should be read only for that user. On Unix systems, this is 0600.

On Windows, follow the tutorial at http://docs.oracle.com/javase/8/docs/technotes/guides/management/security-windows.html to set the correct permissions. If you are running the service under the Local System Account, the user that owns the file and has access to it should be SYSTEM.

With this setup, you should be able to connect to JMX monitoring of the Neo4j server using <IP-OF-SERVER>:3637, with the username monitor and the password Neo4j.

Note that it is possible that you have to update the permissions and/or ownership of the conf/jmx.password and conf/jmx.access files — refer to the relevant section in conf/neo4j.conf for details.

For maximum security, please adjust at least the password settings in conf/jmx.password for a production installation.

For more details, see: http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html.

9.2. How to connect to a Neo4j instance using JMX and JConsole

First, start your Neo4j instance, for example using

$NEO4j_HOME/bin/neo4j start

Now, start JConsole with

$JAVA_HOME/bin/jconsole

Connect to the process running your Neo4j database instance:

Figure 9.1. Connecting JConsole to the Neo4j Java process
Connecting with JConsole

Now, beside the MBeans exposed by the JVM, you will see an org.neo4j section in the MBeans tab. Under that, you will have access to all the monitoring information exposed by Neo4j.

For opening JMX to remote monitoring access, please see Section 9.1, “Adjusting remote JMX access to the Neo4j Server” and the JMX documention.

Figure 9.2. Neo4j MBeans View
Neo4j MBeans view

9.3. How to connect to the JMX monitoring programmatically

In order to programmatically connect to the Neo4j JMX server, there are some convenience methods in the Neo4j Management component to help you find out the most commonly used monitoring attributes of Neo4j. See Section 4.12, “Reading a management attribute” for an example.

Once you have access to this information, you can use it to for instance expose the values to SNMP or other monitoring systems.

9.4. Reference of supported JMX MBeans

Below is a complete reference of Neo4j JMX management beans in two parts. First part shows all beans available in Neo4j Enterprise Edition when the instance is part of a Causal Cluster. The second part shows the management beans that are uniquely available when running in High Availability mode.

For additional information on the primitive datatypes (int, long etc.) used in the JMX attributes, please see Getting Started → Introduction: Properties.

9.4.1. JMX MBeans available on instances in a Causal Cluster

The following JMX management beans are available on instances that are part of a Causal Cluster. One JMX Bean not included here is for the current configuration of the Neo4j instance. For configuration details, see Table A.1, “All settings”.

Table 9.1. MBeans exposed by Neo4j
Name Description

Causal Clustering

Information about an instance participating in a causal cluster.

Diagnostics

Diagnostics provided by Neo4j.

Index sampler

Handle index sampling.

Kernel

Information about the Neo4j kernel.

Locking

Information about the Neo4j lock status.

Memory Mapping

The status of Neo4j memory mapping.

Page cache

Information about the Neo4j page cache. All numbers are counts and sums since the Neo4j instance was started.

Primitive count

Estimates of the numbers of different kinds of Neo4j primitives.

Reports

Reports operations.

Store file sizes

This bean is deprecated, use StoreSize bean instead; Information about the sizes of the different parts of the Neo4j graph store.

Store sizes

Information about the disk space used by different parts of the Neo4j graph store.

Transactions

Information about the Neo4j transaction manager.

Table 9.2. MBean Causal Clustering (org.neo4j.management.CausalClustering) Attributes
Name Description Type Read Write

Information about an instance participating in a causal cluster

RaftLogSize

The total amount of disk space used by the raft log, in bytes

long

yes

no

ReplicatedStateSize

The total amount of disk space used by the replicated states, in bytes

long

yes

no

Role

The current role this member has in the cluster

String

yes

no

Table 9.3. MBean Diagnostics (org.neo4j.management.Diagnostics) Attributes
Name Description Type Read Write

Diagnostics provided by Neo4j

DiagnosticsProviders

A list of the ids for the registered diagnostics providers.

List (java.util.List)

yes

no

Table 9.4. MBean Diagnostics (org.neo4j.management.Diagnostics) Operations
Name Description ReturnType Signature

dumpAll

Dump diagnostics information to JMX

String

(no parameters)

dumpToLog

Dump diagnostics information to the log.

void

(no parameters)

dumpToLog

Dump diagnostics information to the log.

void

java.lang.String

extract

Operation exposed for management

String

java.lang.String

Table 9.5. MBean Index sampler (org.neo4j.management.IndexSamplingManager) Operations
Name Description ReturnType Signature

triggerIndexSampling

triggerIndexSampling

void

java.lang.String,java.lang.String,boolean

Table 9.6. MBean Kernel (org.neo4j.jmx.Kernel) Attributes
Name Description Type Read Write

Information about the Neo4j kernel

DatabaseName

The name of the mounted database

String

yes

no

KernelStartTime

The time from which this Neo4j instance was in operational mode.

Date (java.util.Date)

yes

no

KernelVersion

The version of Neo4j

String

yes

no

MBeanQuery

An ObjectName that can be used as a query for getting all management beans for this Neo4j instance.

javax.management.ObjectName

yes

no

ReadOnly

Whether this is a read only instance

boolean

yes

no

StoreCreationDate

The time when this Neo4j graph store was created.

Date (java.util.Date)

yes

no

StoreId

An identifier that, together with store creation time, uniquely identifies this Neo4j graph store.

String

yes

no

StoreLogVersion

The current version of the Neo4j store logical log.

long

yes

no

Table 9.7. MBean Locking (org.neo4j.management.LockManager) Attributes
Name Description Type Read Write

Information about the Neo4j lock status

Locks

Information about all locks held by Neo4j

java.util.List<org.neo4j.kernel.info.LockInfo> as CompositeData[]

yes

no

NumberOfAvertedDeadlocks

The number of lock sequences that would have lead to a deadlock situation that Neo4j has detected and averted (by throwing DeadlockDetectedException).

long

yes

no

Table 9.8. MBean Locking (org.neo4j.management.LockManager) Operations
Name Description ReturnType Signature

getContendedLocks

getContendedLocks

java.util.List<org.neo4j.kernel.info.LockInfo> as CompositeData[]

long

Table 9.9. MBean Memory Mapping (org.neo4j.management.MemoryMapping) Attributes
Name Description Type Read Write

The status of Neo4j memory mapping

MemoryPools

Get information about each pool of memory mapped regions from store files with memory mapping enabled

org.neo4j.management.WindowPoolInfo[] as CompositeData[]

yes

no

Table 9.10. MBean Page cache (org.neo4j.management.PageCache) Attributes
Name Description Type Read Write

Information about the Neo4j page cache. All numbers are counts and sums since the Neo4j instance was started

BytesRead

Number of bytes read from durable storage.

long

yes

no

BytesWritten

Number of bytes written to durable storage.

long

yes

no

EvictionExceptions

Number of exceptions caught during page eviction. This number should be zero, or at least not growing, in a healthy database. Otherwise it could indicate drive failure, storage space, or permission problems.

long

yes

no

Evictions

Number of page evictions. How many pages have been removed from memory to make room for other pages.

long

yes

no

Faults

Number of page faults. How often requested data was not found in memory and had to be loaded.

long

yes

no

FileMappings

Number of files that have been mapped into the page cache.

long

yes

no

FileUnmappings

Number of files that have been unmapped from the page cache.

long

yes

no

Flushes

Number of page flushes. How many dirty pages have been written to durable storage.

long

yes

no

HitRatio

Ratio of hits to the total number of lookups in the page cache

double

yes

no

Hits

Number of page hits. How often requested data was found in memory.

long

yes

no

Pins

Number of page pins. How many pages have been accessed (monitoring must be enabled separately).

long

yes

no

Unpins

Number of page unpins. How many pages have been accessed and are not accessed anymore (monitoring must be enabled separately).

long

yes

no

UsageRatio

The percentage of used pages. Will return NaN if it cannot be determined.

double

yes

no

Table 9.11. MBean Primitive count (org.neo4j.jmx.Primitives) Attributes
Name Description Type Read Write

Estimates of the numbers of different kinds of Neo4j primitives

NumberOfNodeIdsInUse

An estimation of the number of nodes used in this Neo4j instance

long

yes

no

NumberOfPropertyIdsInUse

An estimation of the number of properties used in this Neo4j instance

long

yes

no

NumberOfRelationshipIdsInUse

An estimation of the number of relationships used in this Neo4j instance

long

yes

no

NumberOfRelationshipTypeIdsInUse

The number of relationship types used in this Neo4j instance

long

yes

no

Table 9.12. MBean Reports (org.neo4j.dbms.diagnostics.jmx.Reports) Attributes
Name Description Type Read Write

Reports operations

EnvironmentVariables

Returns a map if the current environment variables

String

yes

no

Table 9.13. MBean Reports (org.neo4j.dbms.diagnostics.jmx.Reports) Operations
Name Description ReturnType Signature

listTransactions

List all active transactions

String

(no parameters)

Table 9.14. MBean Store file sizes (org.neo4j.jmx.StoreFile) Attributes
Name Description Type Read Write

This bean is deprecated, use StoreSize bean instead; Information about the sizes of the different parts of the Neo4j graph store

ArrayStoreSize

The amount of disk space used to store array properties, in bytes.

long

yes

no

LogicalLogSize

The amount of disk space used by the current Neo4j logical log, in bytes.

long

yes

no

NodeStoreSize

The amount of disk space used to store nodes, in bytes.

long

yes

no

PropertyStoreSize

The amount of disk space used to store properties (excluding string values and array values), in bytes.

long

yes

no

RelationshipStoreSize

The amount of disk space used to store relationships, in bytes.

long

yes

no

StringStoreSize

The amount of disk space used to store string properties, in bytes.

long

yes

no

TotalStoreSize

The total disk space used by this Neo4j instance, in bytes.

long

yes

no

Table 9.15. MBean Store sizes (org.neo4j.jmx.StoreSize) Attributes
Name Description Type Read Write

Information about the disk space used by different parts of the Neo4j graph store

ArrayStoreSize

Disk space used to store array properties, in bytes.

long

yes

no

CountStoreSize

Disk space used to store counters, in bytes

long

yes

no

IndexStoreSize

Disk space used to store all indices, in bytes

long

yes

no

LabelStoreSize

Disk space used to store labels, in bytes

long

yes

no

NodeStoreSize

Disk space used to store nodes, in bytes.

long

yes

no

PropertyStoreSize

Disk space used to store properties (excluding string values and array values), in bytes.

long

yes

no

RelationshipStoreSize

Disk space used to store relationships, in bytes.

long

yes

no

SchemaStoreSize

Disk space used to store schemas (index and constrain declarations), in bytes

long

yes

no

StringStoreSize

Disk space used to store string properties, in bytes.

long

yes

no

TotalStoreSize

Disk space used by whole store, in bytes.

long

yes

no

TransactionLogsSize

Disk space used by the transaction logs, in bytes.

long

yes

no

Table 9.16. MBean Transactions (org.neo4j.management.TransactionManager) Attributes
Name Description Type Read Write

Information about the Neo4j transaction manager

LastCommittedTxId

The id of the latest committed transaction

long

yes

no

NumberOfCommittedTransactions

The total number of committed transactions

long

yes

no

NumberOfOpenedTransactions

The total number started transactions

long

yes

no

NumberOfOpenTransactions

The number of currently open transactions

long

yes

no

NumberOfRolledBackTransactions

The total number of rolled back transactions

long

yes

no

PeakNumberOfConcurrentTransactions

The highest number of transactions ever opened concurrently

long

yes

no

9.4.2. High Availability JMX MBeans

The following JMX management beans are unique to instances that are part of a High Availability cluster.

Table 9.17. MBeans exposed by Neo4j in High Availability mode
Name Description

Branched Store

Information about the branched stores present in this HA cluster member.

High Availability

Information about an instance participating in a HA cluster.

Table 9.18. MBean Branched Store (org.neo4j.management.BranchedStore) Attributes
Name Description Type Read Write

Information about the branched stores present in this HA cluster member

BranchedStores

A list of the branched stores

org.neo4j.management.BranchedStoreInfo[] as CompositeData[]

yes

no

Table 9.19. MBean High Availability (org.neo4j.management.HighAvailability) Attributes
Name Description Type Read Write

Information about an instance participating in a HA cluster

Alive

Whether this instance is alive or not

boolean

yes

no

Available

Whether this instance is available or not

boolean

yes

no

InstanceId

The identifier used to identify this server in the HA cluster

String

yes

no

InstancesInCluster

Information about all instances in this cluster

org.neo4j.management.ClusterMemberInfo[] as CompositeData[]

yes

no

LastCommittedTxId

The latest transaction id present in this instance’s store

long

yes

no

LastUpdateTime

The time when the data on this instance was last updated from the master

String

yes

no

Role

The role this instance has in the cluster

String

yes

no

Table 9.20. MBean High Availability (org.neo4j.management.HighAvailability) Operations
Name Description ReturnType Signature

update

(If this is a slave) Update the database on this instance with the latest transactions from the master

String

(no parameters)