--- title: LDAP-based monitoring description: This page covers the Lightweight Directory Access Protocol (LDAP) interfaces for monitoring DS servers. For the same capabilities over HTTP, refer to HTTP-based monitoring. component: pingds version: 8.1 page_id: pingds:monitoring-guide:ldap-monitoring canonical_url: https://docs.pingidentity.com/pingds/8.1/monitoring-guide/ldap-monitoring.html revdate: 2026-02-09T09:34:08Z keywords: ["LDAP", "Monitoring", "Troubleshooting"] section_ids: basic_availability: Basic availability monitoring-health-status-anonymously: Server health (LDAP) monitoring-health-status-ldap: Server health details (LDAP) activity: Activity monitoring-activity-ldap: Active users (LDAP) monitoring-operation-stats-ldap: Request statistics (LDAP) monitoring-work-queue-ldap: Work queue (LDAP) counts: Counts monitoring-acis-ldap: ACIs (LDAP) monitoring-entry-counts-ldap: Database size (LDAP) monitoring-entry-cache-ldap: Entry caches (LDAP) monitoring-groups-ldap: Groups (LDAP) monitoring-subentries-ldap: Subentries (LDAP) indexing: Indexing monitoring-index-reads-ldap: Index use (LDAP) monitoring-index-cost-ldap: Index cost (LDAP) monitoring-logs: Logging monitoring-replication-ldap: Replication monitoring-replication-delay-ldap: Replication delay (LDAP) monitoring-replication-status-ldap: Replication status (LDAP) monitoring-read-privilege: Monitor privilege --- # LDAP-based monitoring | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This page covers the Lightweight Directory Access Protocol (LDAP) *(tooltip: \
\

An open, cross-platform protocol used for interacting with directory services.\

\
)* interfaces for monitoring DS servers. For the same capabilities over HTTP, refer to [HTTP-based monitoring](http-monitoring.html). | DS servers publish whether the server is alive and able to handle requests in the root DSE. They publish monitoring information over LDAP under the entry `cn=monitor`. The following example reads all available monitoring entries: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(&)" ``` The monitoring entries under `cn=monitor` reflect activity since the server started. Many types of metrics are exposed. For details, refer to [LDAP metrics reference](monitoring-metrics-ldap.html). ## Basic availability ### Server health (LDAP) Anonymous clients can monitor the health status of the DS server by reading the `alive` attribute of the root DSE: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --baseDN "" \ --searchScope base \ "(&)" \ alive ``` > **Collapse: Show output** > > ``` > dn: > alive: true > ``` When `alive` is `true`, the server's internal tests have not found any errors requiring administrative action. When it is `false`, fix the errors and either restart or replace the server. If the server returns `false` for this attribute, get error information, as described in [Server health details (LDAP)](#monitoring-health-status-ldap). ### Server health details (LDAP) The default monitor user can check whether the server is alive and able to handle requests on `cn=health status,cn=monitor`: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN "cn=health status,cn=monitor" \ --searchScope base \ "(&)" ``` > **Collapse: Show output** > > ``` > dn: cn=health status,cn=monitor > ds-mon-alive: true > ds-mon-healthy: true > objectClass: top > objectClass: ds-monitor > objectClass: ds-monitor-health-status > cn: health status > ``` When the server is either not alive or not able to handle requests, this entry includes error diagnostics as strings on the `ds-mon-alive-errors` and `ds-mon-healthy-errors` attributes. ## Activity ### Active users (LDAP) DS server connection handlers respond to client requests. The following example uses the default monitor user account to read the metrics about active connections on each connection handler: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-connection*)" \ ds-mon-active-connections-count ds-mon-active-persistent-searches ds-mon-connection ds-mon-listen-address ``` For details about the content of metrics returned, refer to [Metric types reference](monitoring-types.html). ### Request statistics (LDAP) DS server connection handlers respond to client requests. The following example uses the default monitor user account to read statistics about client operations on each of the available connection handlers: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN "cn=connection handlers,cn=monitor" \ "(&)" ``` For details about the content of metrics returned, refer to [Metric types reference](monitoring-types.html). ### Work queue (LDAP) DS servers have a work queue to track request processing by worker threads, and whether the server has rejected any requests due to a full queue. If enough worker threads are available, then no requests are rejected. The following example uses the default monitor user account to read statistics about the work queue: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN "cn=work queue,cn=monitor" \ "(&)" ``` For details about the content of metrics returned, refer to [Metric types reference](monitoring-types.html). To adjust the number of worker threads, refer to the settings for [Traditional Work Queue](../configref/objects-traditional-work-queue.html). ## Counts ### ACIs (LDAP) DS maintains counts of ACIs *(tooltip: \
\

An instruction or rule that can be used to grant or deny access to users to perform operations on a server.\

\
)*: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-aci)" \ ds-mon-entries-acis-count ds-mon-entries-with-aci-attributes-count ds-mon-global-acis-count ``` ### Database size (LDAP) DS servers maintain counts of the number of entries in each backend and under each base DN. The following example uses the default monitor user account to read the counts: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(|(ds-mon-backend-entry-count=*)(ds-mon-base-dn-entry-count=*))" \ ds-mon-backend-entry-count ds-mon-base-dn-entry-count ``` ### Entry caches (LDAP) DS servers maintain entry cache statistics: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-entry-cache)" \ ``` Entry caches for groups have their own monitoring entries. ### Groups (LDAP) The following example reads counts of static, dynamic, and virtual static groups, and statistics on the distribution of static group size: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-groups)" \ ds-mon-dynamic-groups-count ds-mon-static-groups-count ds-mon-virtual-static-groups-count \ ds-mon-static-group-size-less-or-equal-to-100 \ ds-mon-static-group-size-less-or-equal-to-1000 \ ds-mon-static-group-size-less-or-equal-to-10000 \ ds-mon-static-group-size-less-or-equal-to-100000 \ ds-mon-static-group-size-less-or-equal-to-1000000 \ ds-mon-static-group-size-less-or-equal-to-inf ``` At startup time, DS servers log a message showing the number of different types of groups and the memory allocated to cache static groups. ### Subentries (LDAP) DS maintains counts of LDAP subentries: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-subentries)" \ ds-mon-collective-attribute-subentries-count \ ds-mon-password-policy-subentries-count ``` ## Indexing ### Index use (LDAP) DS maintains metrics about index use. The metrics indicate how often an index was accessed since the DS server started. The following example demonstrates how to read the metrics for all monitored indexes: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-backend-index)" ds-mon-index ds-mon-index-uses ``` ### Index cost (LDAP) DS maintains metrics about index cost. The metrics count the number of updates and how long they took since the DS server started. The following example demonstrates how to read the metrics for all monitored indexes: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-backend-index)" ds-mon-index ds-mon-index-cost ``` ## Logging DS maintains a list of supported logging categories. The following example reads the list: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(objectClass=ds-monitor-logging)" ``` ## Replication Monitor the following to ensure replication runs smoothly. Take action as described in these sections and in the troubleshooting documentation for [replication problems](../maintenance-guide/troubleshooting.html#troubleshoot-repl). ### Replication delay (LDAP) The following example uses the default monitor user account to check the delay in replication: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(ds-mon-receive-delay=*)" \ ds-mon-receive-delay ``` > **Collapse: Show output** > > ``` > dn: ds-mon-domain-name=cn=schema,cn=replicas,cn=replication,cn=monitor > ds-mon-receive-delay: > > dn: ds-mon-domain-name=dc=example\,dc=com,cn=replicas,cn=replication,cn=monitor > ds-mon-receive-delay: > > dn: ds-mon-domain-name=uid=monitor,cn=replicas,cn=replication,cn=monitor > ds-mon-receive-delay: > ``` DS replicas measure replication delay as the local delay when receiving and replaying changes. There are two parts to replication delay: *receive delay* and *replay delay*. To understand what's causing replication delay, you must determine which part is responsible for the delay. A replica calculates these local delays based on changes received from other replicas. Therefore, a replica can only calculate delays based on changes it has received. Network outages cause inaccuracy in delay metrics. A replica calculates delay metrics based on times reflecting the following events: * **t0**: the remote replica records the change in its data * **t1**: the remote replica sends the change to a replica server (This time isn't necessary to calculate the delays in the metrics.) * **t2**: the local replica receives the change from a replica server * **t3**: the local replica applies the change to its data This figure illustrates when these events occur: ![Replication change processing events](../_images/repl-delay.svg) Replication keeps track of changes using CSNs *(tooltip: \
\

An opaque string uniquely identifying a single change to directory data and when it occurred.\

\
)*, opaque and unique identifiers for each change that indicate when and where each change first occurred. The **tn** values are CSNs. When the CSNs for the last change received and the last change replayed are identical, the replica has applied all the changes it has received. In this case, there is no known delay. The receive and replay delay metrics are set to 0 (zero). When the last received and last replayed CSNs differ: * *Receive delay* is set to the time **t2** - **t0** for the last change received. Another name for receive delay is current delay. * *Replay delay* is approximately **t3** - **t2** for the last change replayed. In other words, it is an approximation of how long it took the last change to be replayed. As long as replication delay tends toward zero regularly and over the long term, temporary spikes and increases in delay measurements are normal. When all replicas remain connected and yet replication delay remains high and increases over the long term, the high replication delay indicates a problem. Steadily high and increasing replication delay shows that replication is not converging, and the service is failing to achieve eventual consistency. For a current snapshot of replication delays, you can also use the `dsrepl status` command. Learn more in [Replication status](../config-guide/repl-status.html). ### Replication status (LDAP) The following example uses the default monitor user account to check the replication status of the local replica: ```console $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=monitor \ --bindPassword password \ --baseDN cn=monitor \ "(ds-mon-status=*)" \ ds-mon-status ``` > **Collapse: Show output** > > ``` > dn: ds-mon-domain-name=dc=example\,dc=com,cn=replicas,cn=replication,cn=monitor > ds-mon-status: Normal > ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The values in the `Status` column of the command output don't necessarily match the monitoring attribute values.Learn more in the [dsrepl status](../tools-reference/dsrepl.html#dsrepl_status) command reference. | If the status is not `Normal`, how you react depends on the value of the `ds-mon-status` attribute for LDAP, or `ds_replication_replica_status{status}` for Prometheus. | Status | Explanation | Actions to take | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Bad data` | Replication is broken.Internally, DS replicas store a shorthand form of the initial state called a *generation ID*. The generation ID is a hash of the first 1000 entries in a backend, combined with the total number of entries. When the replicas' generation IDs match, the servers can replicate data without user intervention. When the replicas' generation IDs don't match for a given backend, the servers can't replicate the data.This status arises for one of the following reasons:- The replica and the replication server have different generation IDs for the data because the replica began with different data than its peer replicas. - The fractional replication configuration for this replica doesn't match the backend data. For example, you reconfigured fractional replication to include or exclude different attributes, or you configured fractional replication incompatibly on different peer replicas.You must intervene to make sure the replicas with bad data start from the same initial state as their peers. Follow the suggested actions to take. Don't replace or reinitialize the backend data alone. DS stores the generation ID in the backend and in the changelog. The generation IDs in the backend and in the changelog must match on all peer replicas.DS 7.3 introduced this status. Earlier releases included this state as part of the `Bad generation id` status. | Whenever this status displays:1) If fractional replication is configured, make sure the configuration is compatible on all peer replicas. Learn more in [Fractional replication (advanced)](../config-guide/repl-fractional.html). 2) Initialize the replica with `Bad data` online from a replica with good data. Use the `dsrepl initialize` command to initialize the single bad replica. This fixes the bad generation IDs, correcting the problem in the backend and changelog data. Find an example in [Initialize over the network](../config-guide/repl-init.html#init-repl-online). If you can't initialize the replica with `Bad data` online, [remove it](../install-guide/uninstall.html) and [replace it with a new replica](../config-guide/repl-add-replica.html). | | `Full update` | Replication is operating normally.You have chosen to initialize replication over the network.The time to complete the operation depends on the network bandwidth and volume of data to synchronize. | Monitor the server output and wait for initialization to complete. | | `Invalid` | This status arises for one of the following reasons:- The replica has encountered a replication protocol error. This status can arise due to faulty network communication between the replica and the replication server. - The replica has just started, and is initializing. | If this status happens during normal operation:1) Review the replica and replication server error logs, described in [About logs](../logging-guide/about-logs.html), for network-related replication error messages. 2) Independently verify network communication between the replica and the replication server systems. | | `Normal` | Replication is operating normally. | Nothing to do. | | `Not connected` | This status arises for one of the following reasons:- The replica has just started and is not yet connected to the replication server. - The replica cannot connect to a replication server. | If this status happens during normal operation:1) Review the replica and replication server error logs for network-related replication error messages. 2) Independently verify network communication between the replica and the replication server systems. | | `Too late` | The replica has fallen further behind the replication server than allowed by the [replication-purge-delay](../configref/objects-replication-synchronization-provider.html#replication-purge-delay). In other words, the replica is missing too many changes, and lacks the historical information required to synchronize with peer replicas.The replica no longer receives updates from replication servers. Other replicas that recognize this status stop returning referrals to this replica.DS 7.3 introduced this status. Earlier releases included this state as part of the `Bad generation id` status. | Whenever this status displays:1) Reinitialize replication for the replica that is too late. Learn more in [Manual initialization](../config-guide/repl-init.html). | ## Monitor privilege The following example assigns the required privilege to Kirsten Vaughan's entry to read monitoring data, and shows monitoring information for the backend holding Example.com data: ```console $ ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=admin \ --bindPassword password << EOF dn: uid=kvaughan,ou=People,dc=example,dc=com changetype: modify add: ds-privilege-name ds-privilege-name: monitor-read EOF $ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=People,dc=example,dc=com \ --bindPassword bribery \ --baseDN cn=monitor \ "(ds-cfg-backend-id=dsEvaluation)" ``` > **Collapse: Show output** > > ``` > dn: ds-cfg-backend-id=dsEvaluation,cn=backends,cn=monitor > objectClass: top > objectClass: ds-monitor > objectClass: ds-monitor-backend > objectClass: ds-monitor-backend-pluggable > objectClass: ds-monitor-backend-db > ds-cfg-backend-id: dsEvaluation > ds-mon-backend-degraded-index-count: > ds-mon-backend-entry-count: > ds-mon-backend-entry-size-read: > ds-mon-backend-entry-size-written: > ds-mon-backend-filter-indexed: > ds-mon-backend-filter-unindexed: > ds-mon-backend-filter-use-start-time: > ds-mon-backend-is-private: > ds-mon-backend-ttl-entries-deleted: > ds-mon-backend-ttl-is-running: > ds-mon-backend-ttl-last-run-time: > ds-mon-backend-ttl-queue-size: > ds-mon-backend-ttl-thread-count: > ds-mon-backend-untrusted-index-count: > ds-mon-backend-writability-mode: enabled > ds-mon-db-cache-evict-internal-nodes-count: > ds-mon-db-cache-evict-leaf-nodes-count: > ds-mon-db-cache-leaf-nodes: > ds-mon-db-cache-misses-internal-nodes: > ds-mon-db-cache-misses-leaf-nodes: > ds-mon-db-cache-size-active: > ds-mon-db-cache-size-total: > ds-mon-db-cache-total-tries-internal-nodes: > ds-mon-db-cache-total-tries-leaf-nodes: > ds-mon-db-checkpoint-count: > ds-mon-db-log-cleaner-file-deletion-count: > ds-mon-db-log-files-open: > ds-mon-db-log-files-opened: > ds-mon-db-log-size-active: > ds-mon-db-log-size-total: > ds-mon-db-log-utilization-max: > ds-mon-db-log-utilization-min: > ds-mon-db-version: > ```