Statistics and Reporting

The statistics and reporting utilities generate and display various statistics.

By including a utility command in the command line of a job processing definition, you can run the utility at a predetermined time or under a predetermined set of conditions without being present.

Control-M/EM has a periodic statistics feature, which ignores those job run instances with the 2 highest and 2 lowest elapsed run times, retains a maximum sample of 20 periodic statistics per job, retains periodic statistics for 100 days, and performs purge of those periodic statistics whose retention period has passed every 30 minutes. You can change these defaults in the CCM, as described in Gateway parameters

The following table describes the utilities that generate and display various statistics:

Utility

Description

ctmjsa

Compiles and records runtime data from the Statistical Details table.

ctmruninf

Displays runtime data from the Statistical Details table of the Control-M/Server database.

ctm_menu

  • Collects job statistics. By default, Control-M/Server collects job statistics. To change this go to ctm_menu>System Parameters and Shout Destination Tables>System Parameters and select Statistics.

  • Defines Control-M Server statistics collection mode, which is used by the ctmjsa utility to collect summary statistics. To define the Control-M/Server statistics collection mode, see Defining the Control-M/Server Statistics Collection Mode Using the ctm_menu.

ctmstats

Displays and deletes statistical data from the Statistical Summary table of the Control‑M/Server database.

Defining the Control-M/Server Statistics Collection Mode Using the ctm_menu

This procedure describes how to define the Control-M/server statistics collection mode using the ctm_menu utility. The Control-M operational parameter Statistics Mode indicates the mode used by the ctmjsa utility to collect summary statistics.

Begin

  1. In the Control-M Main Menu, enter the number for the Parameter Customization.

  2. In the Parameter customization menu, enter the number for the Advanced Communication and Operational Parameter option.

  3. The Control-M/Server Advanced Parameters window appears.

  4. In the Statistics Mode field, select one of the following from the drop down list:

    • To compile statistics for each Control-M Job Name, Folder, and Host ID where the job was submitted, select JOBNAME.

    • To compile statistics for each Control-M File Name, File library and Host ID, select FILE_NAME or MEMNAME (default).

  5. Click OK.

ctmjsa

The ctmjsa utility compiles runtime data from the Statistical Details table and records it in the Statistics Summary table of the Control‑M/Server database. This utility must be run by a Control‑M/Server user.

To ensure that the Control-M/Server database contains current statistics on all jobs that are executed under Control-M, you should ensure that the ctmjsa utility runs on a daily basis. A partial cleanup of the Statistical Details table is performed by the New Day procedure.

Each time it is run, the ctmjsa utility:

  • Scans the statistical data for jobs that terminated with OK status. The jobs scanned can be limited to a range of dates as described below.

  • Computes the average run time and standard deviation for each job for which data was found.

  • Records the statistical data in a summary table in the ControlM/Server database (from which the data is made available to ControlM/EM).

  • Displays the summary data filtered according to specified parameters.

Statistical data is only accumulated when the Control‑M system parameter Statistics is set to Y. Operational parameter Statistics Mode determines the mode to be used to compile summary statistics: JOBNAME or MEMNAME. The default is MEMNAME.

If the Statistics Mode parameter was changed from File name to JOBNAME or back since the last run of the ctmjsa utility, you can clean up the statistics from the previous mode by running the following command: ctmstats –delete. The Statistics Mode parameter can be changed through ctm_menu by choosing Parameter Customization Menu =>Advanced Communication and Operational Parameters =>Statistics Mode.

For more information about runtime statistical data, see the information about runtime statistics in Control-M Forecast parameters.

Running the ctmjsa Utility

This procedure describes how to run the ctmjsa utility, which compiles runtime data from the Statistical Details table and records it in the Statistics Summary table of the Control‑M/Server database.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

  2. Type one of the following commands:

    • ctmjsa <fromDate> <toDate>

    • ctmjsa -<delta1> -<delta2> <date>

    • ctmjsa -list [ -JOBNAME <jobname> ]

      [ -FILE_PATH <path> ]

      [ -HOST <hostname> ]

    If the Statistics Mode parameter is JOBNAME, FILE_NAME and FILE_PATH fields in the Statistical Summary table are blank. If the Statistics Mode parameter is FILENAME, the Job Name field is blank.

For the Control-M parameter name, see Parameter name cross references.

ctmjsa Utility Parameters

This table describes the ctmjsa utility parameters:

Parameter

Description

<fromDate>

Determines the start date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.

<toDate>

Determines the end date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.

-<delta1>

Determines the unsigned number used to establish the starting date for statistical data to be compiled. This date is determined by subtracting <delta1> from <date>

If <delta1> is 10 and <date> is 991220, the starting date is 991210

-<delta2>

Determines the unsigned number used to establish the ending date for statistical data to be compiled. This date is determined by adding <Delta2> to <Date>

If <Delta2> is 5 and <Date> is 991220, the ending date is 991225

<date>

Determines the date used together with <Delta1> and <Delta2> to determine the range of dates used for compiling statistical data. The date is expressed in yyyymmdd or yymmdd format.

"*"

Specifies that the utility collects all statistical data available without regard to date.

‑list

Displays data from the Statistical Summary table filtered according to specified sub parameters. Use this option after you have updated the summary table. Output includes the Folder name for each job. This information is also available from Control‑M/EM in the Statistics window.

Filter

Specifies one of the following options and its sub parameter, or specify the null character " " to display statistics for all jobs. This works the same way as "*", which should be enclosed in quotation marks. ? Represents any single character.

  • ‑JOBNAME <jobname>: Identify the job by Job name parameter.

  • ‑FILE_PATH <path>: Identify jobs by their file_path parameter.

  • ‑HOST <hostname>: Identify jobs by their host group parameter (Agent computer).

ctmjsa Utility Example

The following example describes commands compile statistical data for the 5-day period from June 21, 2021 through June 25, 2021 (assuming this data is available). In the second command, the hyphens indicate the beginning of unsigned parameter values; they are not minus signs.

ctmjsa 210621 210625

ctmjsa -3 -1 210624

The following command compiles statistical data using all data currently available:

ctmjsa "*"

This command displays summary data for all jobs whose FILE_NAME parameter starts with "pgmac": ctmjsa -list -FILE_NAME "pgmac*"
A report similar to the following is displayed:

Copy 
FILE_NAME	 FILE_PATH    	 HOST	     CPU [sec]	  ELAPSED (sec)	 FOLDER
.........    .............      ......       .........    .............       ....................
pgmacct1	 prod.acct.pgm	  Diana	     0.19	      233.15	        connection profileq1
pgmacct2	 prod.acct.pgm	  Verdi	     0.12	      6.12	          connection profiletq2
pgmacct3	 prod.acct.pgm	  Diana	     0.05	      170.45	        connection profiletq3
pgmacct4	 prod.acct.pgm	  Diana	     0.34	      145.23	        connection profileq4

ctmruninf

You can use the following utilities to display (and delete) statistical data:

  • The ctmruninf utility displays and deletes data from the Statistical Details table of the Control-M/Server database. An option is available to delete data from this table. The jobs scanned for both options can be limited to a range of dates as described below.

  • Statistical data is only accumulated when the ControlM/Server system parameter Statistics is set to Y.

  • The ctmstats utility displays and deletes data from the Statistical Summary table. For more information about the ctmstats utility, see ctmstats.

Both utilities can be filtered according to date and job information.

The ctmruninf utility displays runtime data from the Statistical Details table of the Control‑M/Server database. For more information about runtime statistical data, see the information about runtime statistics in Control-M Forecast parameters.

Running the ctmruninf Utility

This procedure describes how to run the ctmruninf utility, which enables you to display runtime data from the Statistical Details table of the Control‑M/Server database.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

  2. Type one of the following commands:

    ctmruninf -list <fromDate> <toDate> [<filter>] [-total]

    ctmruninf -list "*" [<filter>] [-total]

    ctmruninf -delete <fromDate> <toDate>

    ctmruninf -PURGE

ctmruninf Utility Parameters

The following table describes the ctmruninf utility parameters:

Parameter

Description

‑list

Displays data from the Statistical Details table within the dates specified in the From Date and To Date parameters. The data listed can be limited by using the Filter subparameter described in this table.

‑delete

Deletes data from the Statistical Details table in the range specified in the From Date and To Date parameters.

<From Date>

Determines the start date of statistical data to be displayed or deleted.

Format: yyyymmddhhmmss

<To Date>

End date of statistical data to be displayed or deleted.

Format: yyyymmddhhmmss

"*"

Specifies that the utility should list all statistical data currently available, without regard to date.

<Filter>

Specify one of the following options and its associated subparameter or leave blank to display the statistics for all jobs in the range.

  • JOBNAME <jobName>: Identify the job by the first 10 characters in its Job Name parameter.

  • FILE_NAME <file name>: Identify the job by its file name parameter.

  • FILE_PATH <path>: Identify jobs by their file path parameter specifications.

  • HOSTID <hostid>: Identify jobs by their Host ID parameter (Agent computer).

  • -ORDERID <orderid>: Identify jobs by their Order ID parameter.

Each of the sub parameters in the filter can include the following wildcard characters:

* represents any number of characters (including none). Any parameter including * should be enclosed in quotation marks (see the third example below).

? represents any single character

‑total

Displays the total CPU and elapsed times for the jobs selected.

-purge

Purges data from the Statistical Details table based on the number of job executions.

Running the ctmruninf utility with the -PURGE option performs the statistics clean up as if it was done during New Day with the RUNINF_PURGE_MODE set to 0.

Default: 0

The Statistics algorithm (JOBNAME or MEMNAME) and the RUNINF_PURGE_LIMIT parameter are taken from the config.dat table, if configured.

You can speed up the New Day procedure by specifying N for the STATISTICS_CLEANUP_IN_NEWDAY parameter and running ctmruninf -PURGE in a job that is run daily. Only the last n run information records of a job are kept, where n is the value of RUNINF_PURGE_LIMIT (default 20).

ctmruninf Utility Example

The following example describes command displays runtime data for the period January 21, 2021 through January 25, 2021, assuming that this data is available:

ctmruninf -list 20210121000000 20210125235959

The following command deletes the statistical data for January 31, 2021:

ctmruninf -delete 20210131000000 20210131235959

The following command causes the utility to display and total runtime data for all jobs on Agent computer Diana.

ctmruninf -list "*" -HOSTID "Diana" -total

A report similar to the following is displayed:

Copy 
TIMESTAMP   JOBNAME  ORDERID  RUN# HOST 	FILE_NAME    FILE_PATH        CPU   ELAPSED 
 ------------- ---------- -------- ---- ------------ ---------- -------------- ----- -------
2021012160524 acct12     00000007    1 Diana        pgmacct    prod.acct.pgm   0.19  233.15
2021012161205 gen786     0000000b    1 Diana        genx       prod.general    0.12    6.12
2021012162311 acct14     00000011    1 Diana        pgmacct    prod.acct.pgm   0.05  170.45
2021012164512 acct15     00000012    1 Diana        pgmacct    prod.acct.pgm   0.14  145.23 
 ------------- ---------- -------- ---- ------------ ---------- -------------- ----- ------- 
Total records printed : 4                                                      0.50  555.35 

ctmstats

The ctmstats utility displays and deletes statistical data from the Statistical Summary table of the Control‑M/Server database. The data scanned for both options can be limited to a range of dates. The Statistical Summary table is created using the ctmjsa utility.

Statistical data is only accumulated when the Control‑M system parameter Statistics is set to Y.

For more information, see System Parameters referred to in ctmsys.

Running the ctmstats Utility

This procedure describes the ctmstats utility, which displays and deletes statistical data from the Statistical Summary table of the Control‑M/Server database.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

  2. Enter the one of the following commands:

    ctmstats -list <fromDate> <toDate> [<filter>] [-total]

    ctmstats -list "*" [<filter>] [-total]

    ctmstats -delete <fromDate> <toDate>

For the Control-M parameter name, see Parameter name cross references.

ctmstats Utility Parameters

The following table describes the ctmstats utility parameters:

Parameter

Description

‑list

Displays data from the Statistical Summary table within the dates specified by the From Date and To Date parameters. The data listed can be limited with use of the Filter sub-parameter (see below).

‑delete

Deletes data from the Statistical Summary table in the range specified by the From Date and To Date parameters.

<From Date>

Determines the start date of statistical data to be displayed/deleted.

Format: yyyymmddhhmmss.

<To Date>

Determines the end date of statistical data to be displayed/deleted.

Format: yyyymmddhhmmss.

"*"

Specifies that the utility should list all statistical data currently available, without regard to date.

<Filter>

Specify one of the following options and its associated subparameter or leave blank to display the statistics for all jobs in the range.

  • ‑JOBNAME <jobName>: Identify the job by its Job Name parameter.

  • ‑FILE_NAME <file name>: Identify the job by its File Name parameter.

  • ‑FILE_PATH <file path>: Identify jobs by their File Path parameter.

  • ‑HOSTID <hostid>: Identify jobs by their host id parameter (Agent computer).

  • Each of the subparameters in the filter can include the following wildcard characters:

    • *: Represents any number of characters (including no characters). Any parameter including * should be enclosed in quotation marks (see example below).

    • ?: Represents any single character

‑total

Displays a line that contains the total CPU and elapsed times for the jobs selected.

ctmstats Utility Example

The following example describes the command displays statistical data for the period January 21, 2021 through January 25, 2021 (assuming that this data is available):

ctmstats -list 20210121000000 20210125235959

A report similar to the following is displayed:

Copy 
TIMESTAMP       JOBNAME  HOST  FILE_NAME  FILE_PATH      AVG CPU  AVG ELAPSED
--------------  ------   ------  -------  -------------  -------  -----------
20210122141214  acct12   Diana   pgmacct  prod.acct.pgm  0.19      233.15 
20210122032025  gen786   Diana   genx     prod.general   0.12        6.12 
20210121123111  acct14   Diana   pgmacct  prod.acct.pgm  0.05      170.45 
20210121113512  acct15   Diana   pgmacct  prod.acct.pgm  0.14      145.23

The following command displays statistical data for all jobs on Agent computer Diana:

ctmstats -list "*" -HOSTID Diana -total

The following command deletes the statistical data for January 31, 2021:

ctmstats -delete 20210131000000 20210131235959