PingDirectory

PingDirectory server troubleshooting tools

The Server provides a set of tools that can also be used to obtain information for diagnosing and solving problems.

Server version information

If it becomes necessary to contact your authorized support provider, then it will be important to provide precise information about the version of the PingDirectory server software that is in use. If the server is running, then this information can be obtained from the "cn=Version,cn=monitor" entry. It can also be obtained using the command:

$ bin/status --fullVersion

This command outputs a number of important pieces of information, including:

  • Major, minor, point and patch version numbers for the server.

  • Source revision number from which the server was built.

  • Build information including build ID with timestamp, OS, user, Java and JVM version for the build.

  • Auxiliary software versions: Jetty, JZlib, SNMP4j (SNMP4J, Agent, Agentx), Groovy, LDAP SDK for Java, and the Server SDK.

LDIF connection handler

The PingDirectory server provides an LDIF connection handler that provides a way to request operations that do not require any network communication with the server. This can be particularly helpful if a configuration problem or bug in the server has left a connection handler unusable, or if all worker threads are busy processing operations.

The LDIF connection handler is enabled by default and looks for LDIF files to be placed in the config/auto-process-ldif directory. This PingDirectory server does not exist by default, but if it is created and an LDIF file is placed in it that contains one or more changes to be processed, then those changes will be applied.

Any changes that can be made over LDAP can be applied through the LDIF connection handler. It is primarily intended for administrative operations like updating the server configuration or scheduling tasks, although other types of changes (including changes to data contained in the server) can be processed. As the LDIF file is processed, a new file is written with comments for each change providing information about the result of processing that change.

dbtest tool

The dbtest tool provides a utility that can be used to obtain general information about the data in a backend database. The tool dumps information about entries or keys, and raw data from the database. It can also find keys that have exceeded the entry limit.

For example, the following command can be used to dump a list of all keys in the objectClass.equality that have exceeded the entry threshold:

$ bin/dbtest dump-database-container \
  --backendID userRoot \
  --baseDN "dc=example,dc=com" \
  --databaseName objectClass.equality \
  --onlyExceedingLimit

On a large database, many dbtest operations may take a long time to complete, since every record in the associated database is examined. Use the database name option to list a specific database. The following command displays information about the uid.equality database in the dc=example,dc=com entry container in the userRoot backend.

$ bin/dbtest list-database-containers -n userRoot -b "dc=example,dc=com" -d uid.equality

Index key entry limit

Indexes have keys that maintain a list of matching entries, up to the index entry limit. When that limit is reached, the key will not contain or maintain that list, and will just maintain a count of matching entries. To determine if index keys are approaching their limit, use either the dbtest tool or the verify-index tool.

While the dbtest tool can be used to gather general imformation, the verify-index tool provides statistical data about the percent of entries covered by the keys.

For example, the following command can be used to retrieve a list of keys that have exceeded the entry threshold:

$ bin/verify-index \
  --baseDN dc=example,dc=com \
  --listKeysExceedingIndexEntryLimit

The following is a sample of the data returned:

 [12:06:05]  Checked 6003 entries and found 0 error(s) in 2 seconds (average rate 2453.2/sec)
 [12:06:05]  Statistics for records that have exceeded the entry limit:
 [12:06:05]  The st.equality index has 48 such record(s) limit=100 min=103 max=152 median=118
 [12:06:05]  1. or (152 entries / 2.53% of all entries)
 [12:06:05]  2. ma (132 entries / 2.20% of all entries)
  .....
 [12:06:05]  The id2subtree index has 2 such record(s) limit=4000 min=6000 max=6002 median=6001
 [12:06:05]  1. 1 => dc=example,dc=com (6002 entries / 99.98% of all entries)
  .....
 [12:06:05]  The id2children index has 1 such record(s) limit=4000 min=6000 max=6000 median=6000
 [12:06:05]  1. 2 => ou=People,dc=example,dc=com (6000 entries / 99.95% of all entries)
 [12:06:05]  The objectClass.equality index has 4 such record(s) limit=4000 min=6001 max=6003 median=6001
 [12:06:05]  1. top (6003 entries / 100.00% of all entries)
  .....

Embedded profiler

If the PingDirectory server appears to be running slowly, then it is helpful to know what operations are being processed in the server. The JVM Stack Trace monitor entry can be used to obtain a point-in-time snapshot of what the server is doing, but in many cases, it might be useful to have information collected over a period of time.

The embedded profiler is configured so that it is always available but is not active by default so that it has no impact on the performance of the running server. Even when it is running, it has a relatively small impact on performance, but it is recommended that it remain inactive when it is not needed. It can be controlled using the dsconfig tool or the Administrative Console by managing the "Profiler" configuration object in the "Plugin" object type, available at the standard object level. The profile-action property for this configuration object can have one of the following values:

  • start – Indicates that the embedded profiler should start capturing data in the background.

  • stop – Indicates that the embedded profiler should stop capturing data and write the information that it has collected to a logs/profile{timestamp} file.

  • cancel – Indicates that the embedded profiler should stop capturing data and discard any information that it has collected.

Any profiling data that has been captured can be examined using the profiler-viewer tool. This tool can operate in either a text-based mode, in which case it dumps a formatted text representation of the profile data to standard output, or it can be used in a graphical mode that allows the information to be more easily understood.

Invoking the profile viewer in text-based mode

Steps

  • Run the profile-viewer command and specify the captured log file using the --fileName option.

    Example:
    $ bin/profile-viewer --fileName logs/profile.20110101000000Z

Invoking the profile viewer in GUI mode

Steps

  • Run the profile-viewer command and specify the captured log file using the --fileName option. To invoke GUI mode, add the option --useGUI.

    Example:
    $ bin/profile-viewer --fileName logs/profile.20110101000000Z --useGUI

Oracle Berkeley DB Java Edition utilities

The Oracle Berkeley DB Java Edition (JE) itself provides a number of utilities that can be used for performing various types of low-level debugging in the database environment. These utilities should generally not be used unless you are advised to do so by your authorized support provider, but they provide access to information about the underlying database environment that is not available through any other means.