PingDirectory

Working with the collect-support-data tool

The PingDirectory server provides a significant amount of information about its current state including any problems that it has encountered during processing. If a problem occurs, the first step is to run the collect-support-data tool in the bin directory. The tool aggregates all relevant support files into a zip file that administrators can send to your authorized support provider for analysis. The tool also runs data collector utilities, such as jps, jstack, and jstat plus other diagnostic tools, and bundles the results in the zip file.

The tool can only archive portions of certain log files to conserve space, so that the resulting support archive does not exceed the typical size limits associated with e-mail attachments.

The data collected by the collect-support-data tool varies between systems. However, the tool always tries to get the same information across all systems for the target PingDirectory server. The data collected includes the configuration directory, summaries and snippets from the logs directory, an LDIF of the monitor and RootDSE entries, and a list of all files in the server root.

Server commands used in the collect-support-data tool

This topic applies only to the PingDirectory server.

The following presents a summary of the data collectors that the collect-support-data tool archives in zip format. If an error occurs during processing, you can re-run the specific data collector command and send the results to your authorized support provider.

Data Collector Description

status

Runs status -F to show the full version information of the PingDirectory server (Unix, Windows).

server-state

Runs server-state to show the current state of the PingDirectory server process (Unix, Windows).

JDK commands used in the collect-support-data tool

This topic applies only to the PingDirectory server.

Data Collector Description

jps

Java Virtual Machine Process status tool. Reports information on the JVM (Linux, Windows, Mac OS).

jstack

Java Virtual Machine Stack Trace. Prints the stack traces of threads for the Java process (Linux, Windows, Mac OS).

jstat

Java Virtual Machine Statistics Monitoring Tool. Displays performance statistics for the JVM (Linux, Windows, Mac OS).

jinfo

Displays the Java configuration information for the Java process (Linux, Windows, Mac OS).

Linux commands used in the collect-support-data tool

This topic applies only to the PingDirectory server.

Data Collector Description

tail

Displays the last few lines of a file. Tails the /var/logs/messages directory.

uname

Prints system, machine, and operating system information.

ps

Prints a snapshot of the current active processes.

df

Prints the amount of available disk space for file systems in 1024-byte units.

cat

Concatenates the following files and prints to standard output:

  • /proc/cpuinfo

  • /proc/meminfo

  • /etc/hosts

  • /etc/nsswitch.conf

  • /etc/resolv.conf

netstat

Prints the state of network interfaces, protocols, and the kernel routing table.

ifconfig

Prints information on all interfaces.

uptime

Prints the time the server has been up and active.

dmesg

Prints the message buffer of the kernel.

vmstat

Prints information about virtual memory statistics.

iostat

Prints disk I/O and CPU utilization information.

mpstat

Prints performance statistics for all logical processors.

pstack

Prints an execution stack trace on an active processed specified by the pid.

top

Prints a list of active processes and how much CPU and memory each process is using.

MacOS commands used in the collect-support-data tool

This topic applies only to the PingDirectory server.

Data Collector Description

uname

Prints system, machine, and operating system information.

uptime

Prints the time the server has been up and active.

ps

Prints a snapshot of the current active processes.

system_profiler

Prints system hardware and software configuration.

vm_stat

Prints machine virtual memory statistics.

tail

Displays the last few lines of a file. Tails the /var/log/system.log directory.

netstat

Prints the state of network interfaces, protocols, and the kernel routing table.

ifconfig

Prints information on all interfaces.

df

Prints the amount of available disk space for file systems in 1024-byte units.

sample

Profiles a process during an interval.

Invoking the collect-support-data tool as an administrative task

This topic applies only to the PingDirectory server.

You can invoke collect-support-data as an administrative task, including as a recurring task that can be automatically invoked on a regular basis.

For more information, see About recurring tasks and task chains.

Available tool options

The collect-support-data tool has some important options that you should be aware of:

  • --noLdap. Specifies that no effort should be made to collect any information over LDAP. This option should only be used if the server is completely unresponsive or will not start and only as a last resort.

  • --pid {pid}. Specifies the ID of an additional process from which information is to be collected. This option is useful for troubleshooting external server tools and can be specified multiple times for each external server, respectively.

  • --sequential. Use this option to diagnose “Out of Memory” errors. The tool collects data in parallel to minimize the collection time necessary for some analysis utilities. This option specifies that data collection should be run sequentially as opposed to in parallel. This action has the effect of reducing the initial memory footprint of this tool at a cost of taking longer to complete.

  • --reportCount {count}. Specifies the number of reports generated for commands that supports sampling (for example, vmstat, iostat, or mpstat). A value of 0 (zero) indicates that no reports will be generated for these commands. If this option is not specified, it defaults to 10.

  • --reportInterval {interval}. Specifies the number of seconds between reports for commands that support sampling (for example, mpstat). This option must have a value greater than 0 (zero). If this option is not specified, it default to 1.

  • --maxJstacks {number}. Specifies the number of jstack samples to collect. If not specified, the default number of samples collected is 10.

  • --collectExpensiveData. Specifies that data on expensive or long running processes be collected. These processes are not collected by default, because they will impact the performance of a running server.

  • --comment {comment}. Provides the ability to submit any additional information about the collected data set. The comment will be added to the generated archive as a README file.

  • --includeBinaryFiles. Specifies that binary files be included in the archive collection. By default, all binary files are automatically excluded in data collection.

  • --adminPassword {adminPassword}. Specifies the global administrator password used to obtain dsreplication status information.

  • --adminPasswordFile {adminPasswordFile}. Specifies the file containing the password of the global administrator used to obtain dsreplication status information.

  • --outputPath. Specifies the path (and optionally, the name) for the support data archive file. If the path specifies a filename, the archive is written to that file. If the path specifies a directory, the file is written into that directory with a server-generated name.

  • --useRemoteServer. Invokes the tool against a remote server instance and streams the output and resulting support data archive back to the client. This option can be especially useful when the server instance is running in a container because it might otherwise be difficult to invoke commands or access files in that container. See also: --proxyToServerAddress and --proxyToServerPort.

  • --proxyToServerAddress and --proxyToServerPort. Use these options with --useRemoteServer to indicate that the support data archive should be retrieved from a server that is not directly accessible but can be accessed through a PingDirectoryProxy server.

  • --securityLevel. Specifies the degree to which the tool will attempt to obscure or omit potentially sensitive information. A value of none indicates that the tool will not attempt to obscure or redact any information. A value of obscure-secrets indicates that the tool will attempt to obscure secret information (like the values of sensitive configuration properties) and omit log files containing user data (like the data recovery log). A value of maximum indicates that the tool will take even more drastic measures, like omitting access log files and obscuring attribute values in entry DNs and search filters, but at the risk of omitting information that could be useful in investigating the associated issue. If this is not provided, a value of obscure-secrets will be used by default.

Running the collect-support-data tool

Steps

  1. Go to the server root directory.

  2. Use the collect-support-data tool. Make sure to include the host, port number, bind DN, and bind password.

    Example:

    $ bin/collect-support-data --hostname 127.0.0.1 --port 389 \
      --bindDN "cn=Directory Manager" --bindPassword secret
  3. Email the zip file to your Authorized Support Provider.