How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 11, 2023

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
Note

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

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.

Some key baseDNs to search are:

baseDN Details
cn=monitor Provides general server information (an example of the type of information returned is shown below).
cn=Disk Space Monitor,cn=monitor Provides information about disks, including disk location and space available.
cn=Work Queue,cn=monitor Provides information about the work queue, including its backlog, average and max backlog.
cn=jvm,cn=monitor Provides information about the system and the JVM, including memory usage.
cn=LDAP,cn=connection handlers,cn=monitor Provides information about all open client connections.
ds-cfg-backend-id=userRoot,cn=Backends,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 want to check the ds-mon-current-delay attribute, which can signify issues with replication if it does not equal 0.

Monitoring operation statistics

You can monitor operation statistics using a command similar to the following: $ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-monitor-ldap-connection-handler)" \*

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, which only increments when the queue is full.
  • ds-mon-requests-in-queue, which indicates queue size.

Monitoring database size

You can monitor the database size using a command similar to the following:$ ./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=*))" \*

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

  • ds-mon-backend-entry-count shows the total number of entries in the backends.
  • ds-mon-base-dn-entry-count 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:$ ./ldapsearch --port 389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "cn=monitor" --searchScope sub "(objectClass=ds-monitor-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

Monitoring Metrics

Monitoring, Logging, and Alerts

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs

N/A


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