JMX-Based Monitoring

A number of tools support Java Management Extensions (JMX), including the jconsole and jvisualvm commands bundled with the Java platform. JMX is not configured by default.

Configure JMX

  1. Set server Java arguments appropriately to avoid regular full garbage collection (GC) events.

    JMX is based on Java Remote Method Invocation (RMI), which uses references to objects. By default, the JMX client and server perform a full GC periodically to clean up stale references. As a result, the default settings cause JMX to cause a full GC every hour.

    To prevent hourly full GCs when using JMX, add the -XX:+DisableExplicitGC option to the list of start-ds.java-args arguments. You can do this by editing the config/java.properties file and restarting the server.

    Avoid using this argument when importing LDIF online using the import-ldif command. The import process uses GC to work around memory management issues.

  2. Configure the server to activate JMX access.

    The following example uses the reserved port number, 1689:

    $ dsconfig \
     create-connection-handler \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --handler-name JMX \
     --type jmx \
     --set enabled:true \
     --set listen-port:1689 \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt

    The change takes effect immediately.

Connect Over JMX

  1. Add appropriate privileges to access JMX monitoring information.

    By default, no users have privileges to access the JMX connection. The following commands add JMX privileges for the directory superuser:

    $ ldapmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN uid=admin \
     --bindPassword password << EOF
    dn: uid=admin
    changetype: modify
    add: ds-privilege-name
    ds-privilege-name: jmx-notify
    ds-privilege-name: jmx-read
    ds-privilege-name: jmx-write
    EOF

    The directory superuser already has the monitor-read privilege. When setting privileges for a regular user, add ds-privilege-name: monitor-read to the list.

  2. Connect using the service URI, username, and password:

    Service URI

    Full URI to the service including the hostname or IP address and port number for JMX where the DS server listens for connections.

    For example, if the server hostname is localhost, and the DS server listens for JMX connections on port 1689, then the service URI is service:jmx:rmi:///jndi/rmi://localhost:1689/org.opends.server.protocols.jmx.client-unknown.

    Username

    The full DN of the user with privileges to connect over JMX, such as cn=My App,ou=Apps,dc=example,dc=com.

    Password

    The bind password for the user.

    1. Configure security and connect remotely.

      See the section on Using SSL in Monitoring and Management Using JMX Technology for hints.

    2. Connect to a local server process using the process ID:

      $ jvisualvm --openpid $(</path/to/opendj/logs/server.pid)