PingAuthorize

Working with the collect-support-data tool

If a problem occurs with PingAuthorize Server, the first step is to run the collect-support-data tool in the bin directory.

The server provides a significant amount of information about its current state, including any problems that it has encountered during processing. The collect-support-data 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 then bundles the results in the .zip file.

The tool may 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 PingAuthorize Server. The data collected includes the configuration directory, summaries and snippets from the logs directory, monitor entry status, and a list of all files in the server root.

Server commands used in the collect-support-data tool

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

Run status -F to show the full version information of PingAuthorize Server (Unix, Windows).

server-state

Run server-state to show the current state of the PingAuthorize Server process (Unix, Windows).

JDK commands used in the collect-support-data tool

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

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

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

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

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 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. If this option is not specified, it defaults 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 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.

--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.

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=Authorize Manager" --bindPassword secret

  3. Email the .zip file to your Authorized Support Provider.