UnboundID LDAP SDK for Java

Interacting with Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server Monitor Data

The UnboundID LDAP SDK for Java provides support for retrieving and interpreting monitor data from a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server instance. Currently supported monitor entries include:

• The general monitor entry, which provides information about the server, including the time that it started and the length of time it has been online, the current, maximum concurrent, and total number of connections established since startup, and product and vendor information.
  
  
• The active operations monitor entry, which provides a summary of the operations currently being processed within the server.
  
  
• Backend monitor entries, which can provide information about each backend defined in the server, including the backend ID, base DNs, total entries (overall and per base DN), whether the backend is writable, and whether the backend is marked private.
  
  
• The client connection monitor entry, which provides information about all client connections currently established to the server.
  
  
• Connection handler monitor entries, which can provide information about each connection handler defined in the server, including the listen addresses and ports, the protocol it uses, the number of connections currently established to the connection handler, and information about each of those connections.
  
  
• The disk space usage monitor entry, which provides information about server components that may consume a significant amount of disk space, and whether the system may be low on usable disk space.
  
  
• The entry cache monitor entry, which provides information about the current and maximum sizes and entry counts for the cache, the number of cache tries, hits, and misses, and the cache hit ratio.
  
  
• JE environment monitor entries, which provide information about Berkeley DB Java Edition databases used by some backends, including the backend ID and JE version.
  
  
• LDAP external server monitor entries, which provide information about the backend servers used by the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Proxy Server, including the address, port, and communication security level, the current health of the server, and the state of the connection pool(s) used to communicate with that server.
  
  
• LDAP statistics monitor entries, which provide information about the work done by each LDAP connection handler, including the number of bytes and LDAP messages read and written, the number of connections established and closed, and the number of each type of request and response processed.
  
  
• The memory usage monitor entry, which provides information about the memory consumption and garbage collection processing performed within the JVM.
  
  
• The processing time histogram monitor entry, which provides information about the length of time required to process the various types of operations, broken down into user-defined buckets.
  
  
• Replica monitor entries, which provide information about the state of a replica for a specified portion of the server DIT, including the base DN, replica ID, generation ID, and information about its communication with the replication server.
  
  
• Replication server monitor entries, which provide information about the state of a replication server, including the replication server ID, replicated base DNs and generation IDs, and the port number on which the replication server is listening.
  
  
• Replication summary monitor entries, which provide information about replication state for a specified portion of the server DIT, including the base DN as well as information about each replica and replication server associated with that base DN.
  
  
• The stack trace monitor entry, which provides a stack trace of the JVM being used to run the server.
  
  
• The system info monitor entry, which provides information about the system and JVM on which the server is running.
  
  
• The traditional work queue monitor entry, which provides information about the state of the server work queue, including the current, average, and maximum observed backlog, the total number of requests submitted, and the number of requests that were rejected because the work queue was full. Note that this will only be available when the Directory Server is configured to use the traditional work queue rather than the UnboundID work queue.
  
  
• The UnboundID work queue monitor entry, which provides information about the state of the server work queue, including the current, average, and maximum observed work queue sizes, and the number of requests that were rejected because the work queue was full. Note that this will not be available if the Directory Server is configured to use the traditional work queue rather than the UnboundID work queue.
  
  
• The version monitor entry, which provides detailed version information about the server.
  
  

Monitor Entries

The Directory Server monitor information is made available in the form of monitor entries. All monitor entries have some common properties, and then each specific type of monitor entry has a number of methods that may be used to obtain specific information about the data provided by the server for the associated monitor type.

The information that is available for all types of monitor entries includes:

• The name of the monitor entry. This will be the RDN value for the entry in the server.
• The display name for the monitor entry, which is a user-friendly name for the entry.
• A description of the monitor entry and the kind of information that it provides.
• A map containing the parsed set monitor attributes for that monitor entry. This will be examined in more detail below.
• Access to the Entry object from which the monitor information was extracted.

Specific types of monitor entries also provide ways of getting access to the information that they provide. For example, the version monitor entry provides the following methods that may be used to get different elements related to the server version:

• getProductName()
• getShortProductName()
• getFullVersion()
• getCompactVersion()
• getMajorVersion()
• getMinorVersion()
• getPointVersion()
• getBuildID()
• getBuildNumber()
• getRevisionNumber()
• getVersionQualifier()
• getFixIDs()

Monitor Attributes

As described above, each specific type of monitor entry provides methods that may be used to access the different kinds of information that type of monitor entry provides. This is very useful if you know exactly the type of information that you wish to retrieve, but it is not very useful for a generic application that wishes to access any of the monitor information without hard-coding methods to get access to the available information. While it would certainly be possible to simply retrieve the entries from the server and display the attribute names and values, this is not ideal because the attribute names are not user friendly or localizeable and in some cases may not be fully self-explanatory, and it is not always easy to determine the data type for the associated information.

To solve these problems and make the monitor data available in a generic but still very useful way, the UnboundID LDAP SDK for Java provides the "public Map<String,MonitorAttribute> getMonitorAttributes()" method in each monitor entry. Each MonitorAttribute object provides the following information:

• A name, which uniquely identifies the monitor attribute within the monitor entry and is the key used to access that monitor entry in the map returned by the getMonitorAttributes method. This name isn't intended to be displayed to the end user, but rather to allow easier lookup of the associated data.
  
  
• A human-readable and localizeable display name, which is suitable for presenting to the end user.
  
  
• A human-readable and localizeable description, which describes the kind of information held in that attribute.
  
  
• A class that represents the type of information held in the monitor attribute. It will be one of the following classes: Boolean, Date, Double, Long, or String.
  
  
• One or more values containing the actual data for the associated monitor attribute.
  
  

Using the information provided by monitor attributes, it possible for an application to obtain and interact with server monitor data in a generic manner and yet still interact with it and/or present it to end users in a useful and meaningful way.

The Monitor Manager

The MonitorManager class provides an interface for accessing the monitor data provided by the server. The"public List<MonitorEntry> getMonitorEntries(LDAPConnection connection)" method can be used to retrieve all of the monitor entries provided by the server, parsed as their appropriate monitor entry subtypes. However, if you are interested in obtaining a specific set of monitor information, then there are methods available for getting each specific type of monitor entry (e.g., the getBackendMonitorEntries method will retrieve all of the backend monitor entries provided by the server).