IBM Support

Using pdcollect in an IBM Tivoli Monitoring (ITM) Environment

Question & Answer


Question

Instructions are provided for using pdcollect in an IBM Tivoli Monitoring V6.3.0 environment.  Although earlier releases of IBM Tivoli Monitoring are no longer supported, included here are special conditions for varying functionality in different 6.x releases.

Answer

The most common set of arguments for pdcollect that suits most environments in IBM Tivoli Monitoring 6.x.x is the following:

tacmd pdcollect -o nohist -f

Running the command can require a few minutes to process all the data and requests.

Most of the time, a user will not need to add/remove data to the package and can always retrieve such data externally from the tool, so "-f" is used to make the tool completely non-interactive. Also, "-o nohist" is used because there are frequently large historical data files on a system, especially when pdcollect is run on a TEMS storing historical data, so you usually want to avoid collecting those files.
Special Note for Windows Users: To collect relevant information, it is recommended that you run all commands in Administrator mode.

Alternative Scenarios and Recommendations

Including Historical Data: If the tool is run on a TEMS, and historical data collection is storing historical data on that TEMS, then it's possible that the number and size of the history files can be considerable. Or, if the tool is run on an Agent, historical data collection is configured to store data on the Agent, and there are a large number of attribute groups or Agent instances collecting data on that physical system, the number of historical data files can be considerable also. However, suppose you are sure you need to collect these files to troubleshoot an issue related to historical data. In that case, you can enable it by removing the "-o nohist" argument above. For example:

tacmd pdcollect -f

  • Getting TEPS migrate-export data included on UNIX and Linux: If you are running on the TEPS system on UNIX and Linux, and want to have it run a migrate-export on the TEPS automatically and include it in the pdcollect, then add the "-m" option. For example:

tacmd pdcollect -o nohist -f -m

  • Only particular logfiles are needed by Support. However, all the other pdcollect data is still needed: The pdcollect "-nologs" argument will avoid getting logs, and avoiding the "-f" argument allows a user to copy only those files that are needed later when prompted with the "Type "exit" when done>" prompt. For example:

tacmd pdcollect -o nologs

After it collects the data, it will show a prompt like this:

********************************************************************
  • Data collection is complete.
    Files are stored under the C:\Users\IBM_AD~1\AppData\Local\Temp\pdcollect-host1231393464034433 directory.

    You will now be allowed to examine the files, edit them to remove information you do not want to expose to IBM or add additional files to the set.

    Enter "exit" when you are finished.

    Any files which are left will be archived in preparation for
    transmission to IBM.
    ********************************************************************
    Type "exit" when done>
    ====================================================

    This allows you to open another shell prompt, terminal, or window to look at the contents of the indicated directory and add/remove content. The temporary working directory is indicated in the above line, "Files are stored under...."

    When you are finished, you can return to this window above, and at the "Type "exit" when done>" prompt, type "exit" to allow pdcollect to complete.

  • Disk space issues: If the issue is that the filesystem has low space where the temporary working path is located (default /tmp), the user can add the "-d" argument and specify a different path for the pdcollect command to use. For example:

tacmd pdcollect -d /home/user1/newdir -o nohist -f
Windows Event Log data not needed: On Windows, adding "-noevent" argument will prevent it from gathering Windows Event Log data ("Warning" and "Error" event entries). Due to the large number of events in some of these logs can require a long time to process. So if you're reasonably certain you won't need event-type data to analyze, you can use the "-noevent" argument to skip it. For example:

tacmd pdcollect -o noevent -f
Too many logs, causing pdcollect to fail to copy the logs subdirectory: A user may see a message indicating problems copying files from the main "logs" subdirectory when running the pdcollect tool on a system with a large number of components installed on it (such as a stand-alone test environment), or a system with a large number of Agent instances on it, due to the subsequent large number of logs present. Afterward, the user will notice that it didn't copy any of the logs and that an error occurred:

================
Collecting log files...
/bin/ksh: /usr/bin/cp: 0403-027 The parameter list is too long.
================

Consider running "tacmd pdcollect -o nologs" and manually copying just the needed files.


Sample Output:

This example shows a run in a Windows IBM Tivoli Monitoring 6.3 environment:
====================================
C:\test>tacmd pdcollect -o nohist noevent nologs -f -m

KUICPD113I: Executing the pdcollect script from local machine...
KUICPD002I Attempting to connect to the host localhost ...
Please verify that there is enough space for the PDCollect archive.
KUICPD004I Executing the pdcollect script cmd.exe /C C:\IBM\ITM\bin\pdcollect.cmd C:\Users\IBM_AD~1\AppData\Local\Temp\ -nohist
-noevent -nologs -noprompt -nojava -migex ...
Collecting environment information...
Collecting system information...
Collecting disk space information...
Collecting network information...
Collecting registry information...
Collecting running process information...
Collecting configuration files...
Collecting MSG2 files...
Collecting BuildPresentation files...

Collected files will be stored in C:\Users\IBM_AD~1\AppData\Local\Temp\pdcollect-host123.jar...
KUICPD008I The command was completed successfully.
================================================


This example shows a sample run on UNIX and Linux:
================================================
host123:/opt/IBM/ITM# tacmd pdcollect -o nohist nologs -f -m

KUICPD113I: Executing the pdcollect script from local machine...
KUICPD002I Attempting to connect to the host localhost ...
Please verify that there is enough space for the PDCollect archive.
KUICPD004I Executing the pdcollect script /opt/IBM/ITM/bin/pdcollect /tmp -nohist -nologs -noprompt -nojava -migex ...
ITM installation directory is /opt/IBM/ITM
Collecting environment information...
Collecting system information...
Collecting bootup messages...
Collecting release information...
Collecting maintenance information...
Collecting disk space information...
Collecting network information...
Collecting running process information...
Management Server subdirectory is /opt/IBM/ITM/tables/hubtems
Management Server name is hubtems
Collecting database files...
Running migrate-export.sh...
KfwSQLClient to dump node status table...
/opt/IBM/ITM

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The directory
/tmp/pdcollect-host123/autopdzip/autopd/IBM/ITM contains the collected diagnostic information.
Forward the directory contents to your IBM Support representative.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Collected files will be stored in /tmp/pdcollect-host123.jar...
KUICPD008I The command was completed successfully.
=================================================


Older versions: special conditions for IBM Tivoli Monitoring 6.2.1 on Windows

On Windows IBM Tivoli Monitoring 6.2.1, pdcollect did not collect the logs properly. A logs directory may have been in the generated JAR package, but it was empty. APAR IZ42859 was opened for that defect.


Older versions: special conditions for IBM Tivoli Monitoring 6.1

Downloads for an IBM Tivoli Monitoring 6.1 environment:

The pdcollect tool is installed with the product starting with IBM Tivoli Monitoring 6.2. The pdcollect tool is not shipped with IBM Tivoli Monitoring 6.1, so the following files can be used in an (unsupported) IBM Tivoli Monitoring 6.1 environment:

Windows:
  • pdcollect.cmd
  • pdcfilt.exe

UNIX/Linux:
  • pdcollect

z/OS:
  • pdcollect.clist


pdcfilt.exepdcollectpdcollect.clistpdcollect.cmd

Since this version does not depend on tacmd, it is run directly.
Also, it uses a different set of arguments than the "tacmd pdcollect" uses.
For example, "pdcollect -noprompt" is the most common method of running the tool.

Preparation in a 6.x.x UNIX or Linux environment:
  • Place pdcollect in <InstallDirectory>/bin, where <InstallDirectory> is the base directory where IBM Tivoli Monitoring 6.1 is installed (this is commonly referred to as $CANDLEHOME, though it is not by default a predefined environment variable).
  • Use the "chmod" command to make pdcollect executable; for example, "chmod 755 pdcollect".
  • If <InstallDirectory>/bin is not already in the $PATH, then cd to <InstallDirectory>/bin and run the utility using "./pdcollect". If <InstallDirectory>/bin is already in the $PATH, it can be run without the "./" prefix.
  • While it is not necessary to make usage of this and other IBM Tivoli Monitoring 6.x commands simpler, most users will create a script and source it into the environment to preset these variables and make it easier to use. For example, if a file called itm_env.sh in the current working directory contains the following:

    #!/bin/sh
    CANDLEHOME=/opt/IBM/ITM
    export CANDLEHOME
    PATH=$CANDLEHOME/bin:$PATH
    export PATH

    Then this can be sourced into the current shell by doing:

    . ./itm_env.sh (note the initial period "." character, followed by a space, followed by the ./<filename>)

    After sourcing the environment file this way, the pdcollect command, as well as other commands like tacmd and itmcmd, can be run from any directory.
Preparation in a 6.x.x Windows environment:
  • Place pdcollect.cmd and pdcfilt.exe in %CANDLE_HOME%\bin
  • By default, %CANDLE_HOME% is a defined environment variable in Windows, and %CANDLE_HOME%\bin is already part of the %PATH%. So pdcollect can be run from any directory since it's already in the path.


Preparation in a 6.x.x z/OS environment:
  • Download the pdcollect.clist file.
  • Copy the clist file into the RKANSAM dataset as member KMSPDCOL in the RTE of interest
  • From either TSO "READY" or the "TSO Command" panel of ISPF, invoke the clist using the TSO "EXEC" command:

Ex: 'omegamon.testrte.rkanpar(kmspdcol)' 'help'
 

[{"Product":{"code":"SSTFXA","label":"Tivoli Monitoring"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Not Applicable","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"6.1;6.2;6.2.1;6.2.2;6.2.3;6.3","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

IBM Tivoli Monitoring

Document Information

Modified date:
05 July 2023

UID

swg21284703

Page Feedback