IBM Support

Using pdcollect in an ITM Environment

Question & Answer


Question

Instructions are provided for using pdcollect in an ITM V6 environment, including special conditions for varying functionality added in different 6.x releases.

Cause

-

Answer

The most common set of arguments for pdcollect that will suit most environments in ITM 6.2.x and higher 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 external from the tool, so "-f" is used to make the tool completely non-interactive. Also, "-o nohist" is used because frequently there are very large historical data files on a system, especially when pdcollect is run on a TEMS that is storing historical data, so you usually want to avoid collecting those.



Alternative Scenarios and Recommendations



Including Historical Data: If the tool is being 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 very large. Or, if the tool is being run on an Agent, and 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 history data files can be large also. However, if you are sure that you need to collect these files, in order to troubleshoot an issue related to historical data, then you can enable it by removing the "-o nohist" argument above. For example:

tacmd pdcollect -f



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

tacmd pdcollect -o nohist -f -m


     
Only particular logfiles are really needed by Support, but 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 C:\Users\IBM_AD~1\AppData\Local\Temp\pdcollect-host1231393464034433 directory.

    You will now be given an opportunity to examine the files, edit them to
    remove information that 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 / window to look at the contents of the indicated directory and add/remove content. The temporary working directory is indicated in the line above that states "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 finish and 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 simply 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, it can require a long time to process. So if you're fairly 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 standalone test environment), or a system with a large number of Agent instances on it, due to the subsequently large number of logs present. Afterwards, 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.
================

In this case, consider running "tacmd pdcollect -o nologs" and manually copying just the files that are needed.



Sample Output:

This example shows a run in a Windows ITM 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/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 ITM 6.2.1 on Windows

On Windows ITM 6.2.1 GA release, pdcollect did not collect the logs properly. A logs directory may have been in the JAR package that was generated, but it was empty. APAR IZ42859 was opened for that defect. A workaround to fixing the pdcollect.cmd script on a Windows environment was used in the interim, and was documented at http://www-01.ibm.com/support/docview.wss?uid=swg21368486 .



Older versions: special conditions for ITM 6.1

Downloads for an ITM 6.1 environment:

The pdcollect tool is installed with the product starting with ITM 6.2. The pdcollect tool is not shipped with ITM 6.1, so the following files can be used in an ITM 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.1 UNIX/Linux environment:
  • Place pdcollect in <InstallDirectory>/bin, where <InstallDirectory> is the base directory where ITM 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 absolutely necessary, to make usage of this and other ITM 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.1 Windows environment:
  • Place pdcollect.cmd and pdcfilt.exe in %CANDLE_HOME%\bin
  • By default, %CANDLE_HOME% is already 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.1 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":"SSZ8F3","label":"IBM Tivoli Monitoring V6"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"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":""}]

Document Information

Modified date:
19 December 2019

UID

swg21284703