How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I use cn=monitor entry in DS 5.x and 6.x for monitoring?

Last updated Apr 8, 2021

The purpose of this article is to provide information on using the cn=monitor entry in DS for monitoring purposes. DS exposes monitoring information over LDAP under this entry.


1 reader recommends this article

Overview

You can perform a ldapsearch against the cn=monitor entry and sub-entries to provide a variety of statistics that are useful for monitoring DS. 

Note

For DS 7 and later, you should refer to the Monitoring Guide for this information instead: Monitoring Guide › LDAP-Based Monitoring

Some key baseDNs to search are:

Version baseDN Details
All cn=monitor Provides general server information (an example of the type of information returned is shown below).
All cn=Disk Space Monitor,cn=monitor Provides information about disks, including disk location and space available.
All cn=Work Queue,cn=monitor Provides information about the work queue, including its backlog, average and max backlog. 
DS 6.x cn=jvm,cn=monitor

Provides information about the system and the JVM, including memory usage.

Replaces cn=System Information,cn=monitor and cn=JVM Memory Usage,cn=monitor

DS 6.x cn=LDAP,cn=connection handlers,cn=monitor

Provides information about all open client connections.

Replaces cn=Client Connections,cn=monitor

DS 6.x ds-cfg-backend-id=userRoot,cn=Backends,cn=monitor

Provides monitoring information about the Berkeley DB Java Edition backend.

Replaces cn=userRoot Database Environment,cn=monitor

DS 5.x cn=System Information,cn=monitor Provides information about the system and the JVM.
DS 5.x cn=JVM Memory Usage,cn=monitor Provides information about memory usage in the JVM.
DS 5.x cn=Client Connections,cn=monitor Provides information about all open client connections.
DS 5.x cn=userRoot Database Environment,cn=monitor Provides monitoring information about the Berkeley DB Java Edition backend.

Examples

See the following sections for useful monitoring examples:

Note

All the examples use the standard non-secure port (389). You should adjust this according to your environment; in particular, if you are using production mode or have the LDAPS Connection Handler enabled, you should use --port 1636 --useSsl --trustAll instead.

Using the cn=monitor entry

Note

Returning all monitoring information using the below command is a great way to initially find the LDAP metrics and corresponding LDAP attributes that you’re looking to measure; you can then construct specific searches once you know the baseDN and attributes you're interested in.

You can return all monitoring information using a command such as:

$ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=*)" \*

An example output in DS 6 looks like this:

dn: cn=monitor objectClass: top objectClass: ds-monitor objectClass: ds-monitor-server objectClass: extensibleObject ds-mon-product-name: ForgeRock Directory Services ds-mon-short-name: OpenDJ ds-mon-vendor-name: ForgeRock AS. ds-mon-full-version: ForgeRock Directory Services 6.0.0 ds-mon-compact-version: OpenDJ-6.0.0 ds-mon-current-connections: 3 ds-mon-max-connections: 3 ds-mon-total-connections: 17 ... dn: cn=Administration Connector,cn=monitor objectClass: top objectClass: ds-monitor objectClass: ds-monitor-connection-handler objectClass: ds-monitor-ldap-connection-handler ds-mon-config-dn: cn=Administration Connector,cn=config ds-mon-protocol: LDAPS ds-mon-listen-address: 0.0.0.0:6444 ds-mon-active-connections-count: 0 ds-mon-connections: {"count":8,"total":8.000,"mean_rate":0.001,"m1_rate":0.000,"m5_r ate":0.000,"m15_rate":0.000} ds-mon-bytes-read: {"count":474,"total":100877.000,"mean_rate":18.642,"m1_rate":0.00 0,"m5_rate":0.000,"m15_rate":0.676} ds-mon-bytes-written: {"count":1181,"total":444547.000,"mean_rate":82.151,"m1_rate": 0.000,"m5_rate":0.001,"m15_rate":3.112} ds-mon-active-persistent-searches: 0 ds-mon-abandoned-requests: 0 ds-mon-requests-abandon: {"count":0,"total":0.000,"mean_rate":0.000,"m1_rate":0.000, "m5_rate":0.000,"m15_rate":0.000,"mean":0.000,"min":0.000,"max":0.000,"stddev":0.000 ,"p50":0.000,"p75":0.000,"p95":0.000,"p98":0.000,"p99":0.000,"p999":0.000,"p9999":0. 000,"p99999":0.000} ds-mon-requests-add: {"count":3,"total":50.000,"mean_rate":0.001,"m1_rate":0.000,"m5 _rate":0.000,"m15_rate":0.000,"mean":16.707,"min":0.999,"max":37.224,"stddev":15.102 ,"p50":12.059,"p75":12.059,"p95":37.224,"p98":37.224,"p99":37.224,"p999":37.224,"p99 99":37.224,"p99999":37.224} ds-mon-requests-bind: {"count":7,"total":773.000,"mean_rate":0.001,"m1_rate":0.000," m5_rate":0.000,"m15_rate":0.000,"mean":110.414,"min":10.945,"max":272.630,"stddev":7 8.111,"p50":76.022,"p75":126.353,"p95":272.630,"p98":272.630,"p99":272.630,"p999":27 2.630,"p9999":272.630,"p99999":272.630} ...

Alternatively, you can perform more specific searches against individual baseDNs and include particular objectClass parameters and/or attributes to filter the information returned.

Monitoring replication

You can monitor replication for each Directory server and Replication server that the server searched knows about using a command similar to the following:

$ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=Replication,cn=monitor" --searchScope sub "(objectClass=*)" \*

Specifically, you would want to check the following attributes (depending on version), which can signify issues with replication if they do not equal to 0:

  • DS 6.x: ds-mon-current-delay
  • DS 5.x:
    • missing-changes
    • approximate-delay

Monitoring operation statistics

You can monitor operation statistics using a command similar to the following:

  • DS 6.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-monitor-ldap-connection-handler)" \*
  • DS 5.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-connectionhandler-statistics-monitor-entry)" \*

This command returns three sets of statistics:

  • Overall read/write statistics (count of messages, bytes etc).
  • Number of requests and responses per operation.
  • Performance metrics - total counts of each operation finished and the total execution time of these operations.

This final set of statistics can be really useful for monitoring performance. You can also determine average operation times by querying this on a regular basis and calculating the differences from the previous query. Both the average operations per second and elapsedTime per operation can be derived.

Monitoring the work queue

You can monitor the work queue using a command similar to the following:

$ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=Work Queue,cn=monitor" --searchScope sub "(objectClass=*)" \*

This command will give you an understanding of how busy your worker threads are as the queue will typically stay empty if there are free worker threads. This can be seen by checking:

  • ds-mon-requests-rejected-queue-full (requestsRejectedDueToQueueFull in pre-DS 6), which only increments when the queue is full.
  • ds-mon-requests-in-queue (maxRequestBacklog, currentRequestBacklog and averageRequestBacklog in pre-DS 6), which indicates queue size.

Monitoring database size

You can monitor the database size using a command similar to the following:

  • DS 6.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(|(ds-mon-backend-entry-count=*)(ds-mon-base-dn-entry-count=*))" \*
  • DS 5.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-backend-monitor-entry)" \*

This command will return database size details for each backend, where:

  • ds-mon-backend-entry-count (ds-backend-entry-count in DS 5.x) shows the total number of entries in the backends.
  • ds-mon-base-dn-entry-count (ds-base-dn-entry-count in DS 5.x) shows the total number of entries per base DN.

Monitoring active users

You can monitor users who are currently connected to the DS server using a command similar to the following:

  • DS 6.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-monitor-connection*)" \*
  • DS 5.x: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(&(objectClass=ds-monitor-entry)(connection=*))" \*

This command searches the connection handlers and returns the connection attribute. An example output in DS 6 looks like this:

dn: cn=Administration Connector,cn=monitor objectClass: top objectClass: ds-monitor objectClass: ds-monitor-connection-handler objectClass: ds-monitor-ldap-connection-handler ds-mon-config-dn: cn=Administration Connector,cn=config ds-mon-protocol: LDAPS ds-mon-listen-address: 0.0.0.0:4444 ds-mon-active-connections-count: 0 ds-mon-connections: {"count":6,"total":6.000,"mean_rate":0.000,"m1_rate":0.000,"m5_rate":0.000,"m15_rate":0.000} ds-mon-bytes-read: {"count":117,"total":25811.000,"mean_rate":0.084,"m1_rate":0.000,"m5_rate":0.000,"m15_rate":0.000} ds-mon-bytes-written: {"count":241,"total":155863.000,"mean_rate":0.508,"m1_rate":0.000,"m5_rate":0.000,"m15_rate":0.000} ds-mon-active-persistent-searches: 0 ds-mon-abandoned-requests: 0 ... dn: cn=LDAP,cn=connection handlers,cn=monitor objectClass: top objectClass: ds-monitor objectClass: ds-monitor-connection-handler objectClass: ds-monitor-ldap-connection-handler ds-mon-config-dn: cn=LDAP,cn=connection handlers,cn=config ds-mon-protocol: LDAP ds-mon-listen-address: 0.0.0.0:389 ds-mon-connection: {"connID":14,"connectTime":"20190117102734Z","source":"127.0.0.1:36914","destination":"127.0.0.1:389","ldapVersion":3,"authDN":"cn=Directory Manager","ssf":0,"opsInProgress":0,"persistentSearches":0} ds-mon-connection: {"connID":16,"connectTime":"20190117102934Z","source":"127.0.0.1:36920","destination":"127.0.0.1:389","ldapVersion":3,"authDN":"cn=Directory Manager","ssf":0,"opsInProgress":0,"persistentSearches":0} ...

See Also

How do I perform a heartbeat check against DS (All versions)?

How do I check if a backend is online in DS (All versions)?

FAQ: DS performance and tuning

FAQ: Monitoring DS

Reference › Monitoring Metrics

Administration Guide › Monitoring, Logging, and Alerts

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs

OPENDJ-1479 (monitoring data / attributes shown for 'cn=monitor' are not documented)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.