Agent Health Check

The Health Check utility (HCU) collects the environment information and logs, and puts them into a ZIP (Windows only) or TAR.Z (Linux only) file for troubleshooting purposes. This includes information about the Agent host such as the operating system version, patch level, kernel setting, memory consumption, list of running processes, operating system name, error logs, hardware configuration, and network configuration. This program is used at the request of Technical Support to determine the cause of a problem. The Health Check utility (HCU) creates a log file that specifies the processes that ran and the information that was written to the package file. The contents of the log file indicate what proprietary information is included in the package file.

The HCU utility writes log files to the following directories:

  • Log: <AGENT_HOME>/ctm/proclog/ctma_data_collector_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>_display.log

  • HCU Package:

    • Windows: <AGENT_HOME>/hcu_package/ctma_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.zip

    • Linux: ctma_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.tar.Z

Running the Agent Health Check Utility

This procedure describes how to run the Health Check utility with default parameters, which enables you to collect and package the data generally required by BMC Support.

Begin

  1. Navigate to the following directory:

    • Windows: <Agent_Home>\exe

    • Linux: $CONTROLM/exe

  2. Run the following command:

    <Full_Pathname>ctma_data_collector

  3. To view the entire list of actions performed by the utility, see the log file right after executing the utility.

    C:\Program Files\BMC Software\Control-M SaaS Agent\Default\proclog\ctm_data_collector_20201103_110037_MSWin32_vw-tlv-ctm-dvl2_display.log

Agent Health Check Utility Parameters

The following table describes the Health Check utility parameters.

Parameter

Description

Components

(Optional) Products and applications that the utility can gather data.

Category

Determines the Control-M/Agent specific categories for the Health Check utility, as described in Health Check Utility Category Parameters.

Profiles

(Optional) Defines a predefined combination of Components and Categories, as described in Health Check Utility Profile Parameters.

If you specify one or more Profiles, do not specify Components or Categories.

-simulate

(Optional) Simulates execution of a Health Check utility.

This allows the user to verify that specified parameter values are appropriate.

-days

(Optional) Defines the maximum number of days in the past to gather the information.

This option only affects log files relevant to BMC Software components.

Default: 2

-max_size

(Optional) Defines the maximum size (in MB) of the compressed file that is created by the Health Check utility.

Default: 300

-trace

(Optional) Runs a trace on the Health Check utility.

This generates the following log file:

ctm_data_collector_<YYYYMMDD>_<HHMMSS>_<PLATFORM_TYPE>_<HOSTNAME>.log

-verbose

(Optional) Creates an output of the utility processes.

By default, only processed categories appear.

-batch

(Optional) Runs in batch mode without a confirmation request.

-help, -h

(Optional) Displays an explanation of how to use the utility.

Health Check Utility Category Parameters

The following table describes Control-M/EM specific categories for the Health Check utility.

Category

Description

INST_AG

Defines the installation parameters for UNIX and Windows.

If you run the Health Check utility with INST, it gathers relevant information only if the error occurs after the files are copied during the installation. If you specify the INST Category parameter, you must also specify one or more component parameters. If you specify the INST Category parameter, do not specify categories other than INST.

UNIX:

  • Collects the content of the following:

    • BMCINSTALL/installed/

    • BMCINSTALL/log/

    • BMCINSTALL/uninstall/

  • Collects all files with user ownership from the /tmp directory.

  • Lists all directories and folders under the component installation path.

Windows:

  • Collects the content of the following:

    • %temp%\PG*.txt

    • %ALLUSERSPROFILE%\Application Data\PG*.txt

    • <EM_HOME>\bin\DBUtils\DBUData\log\

    • %temp%\*_log.txt

    • %temp%\*_win.txt

  • Lists all directories and folders under the component installation path.

OS

Defines the Operating System related physical resource, as follows:

  • Operating system version

  • Hardware configuration

  • Software, hotfixes, and patches installed

  • Environment variables and files

  • System resource limits

  • Kernel parameters

  • Swap space

  • System and application logs

  • Scheduled tasks

  • Startup files

  • File system information

  • (Windows only) *.ini files

  • Resource consumption

  • List of running processes

  • Network settings

  • Locate and timezone information

BSS

Defines the component backup, sysout and status directories.

CNF

Defines the following component configuration files:

  • Component version that collects the information from installed-version.txt file located in the <AG_HOME> directory

  • (Windows only) Control-M/Agent registry hives export

  • Configuration files under <AG_HOME>/data

  • List of files under home directory

LOG

Defines the following component general diagnostic data collection:

  • All component logs (proclog) for a predefined number of days.

    Default: 2 days

  • Content of the following directories:

    • BACKUP

    • ONSTMT

    • PID

    • PROCID

    • SYSOUT

    • TEMP

    • DAILYLOG

UTL

Defines the component utilities.

This information includes sizes of the following tables:

  • Agent and Application plug in versions

  • Agent communication diagnostics

  • Java version

MSR_AG

Defines the component and environment measurements stored in the database, as follows:

  • Number of Jobs ended OK

  • Number of Jobs ended Not OK

  • Number of “On statement” processing less than 5 seconds

  • Number of “On statement” processing 5 to 60 seconds

  • Number of “On statement” processing 60 seconds to 10 minutes

  • Number of “On statement” processing longer than 10 minutes

  • Number of running jobs

  • Number of submitted jobs

  • Average submit time in seconds

  • Average track time in seconds

Health Check Utility Profile Parameters

The following table describes the profile parameters, which are a predefined combination of Components and Categories.

Profile

Description

ENV

Collects environment data that includes information the OS Category.

AG

Collects Control-M/Agent data.

This includes information from the following Categories:

  • CNF

  • LOG

  • UTL

  • MSR_AG

EXD_BSS

Excludes the collection of backup, sysout and status directories.

Fewer directories provides a lighter option that shortens the amount of time that the Health Check utility needs to run.

- ctma_data_collector -F EXD_BSS

MSR

Collects measurement data that includes information the MSR_AG Category.

LOG_CFG

Collects environment data and Control-M/Agent configuration data.

This includes information from the following Categories:

  • OS

  • CNF

  • LOG

  • UTL

ALL

Collects data through all Control-M/Agent Profiles, as follows:

  • OS

  • CNF

  • LOG

  • UTL

  • MSR_AG