MAT Detect Plug-in for Zowe CLI

The MAT Detect plug-in for Zowe CLI enables you to detect performance issues and access performance data supplied by the Performance Management Assistant component (PMA) of Mainframe Application Tuner. The plug-in ensures interaction of your jobs with the Performance Management Assistant and provides access to PMA functionality.

If you include the MAT Detect plug-in for Zowe CLI in your CI/CD pipeline, the PMA module can measure the performance of your job after each code commit and evaluate the performance based on the previous measurements and the thresholds that you define within PMA. This information can help you detect possible performance degradation of your job at early testing stages, before your code is deployed to the production environment.

Table of Contents
=================
* Installation
* Prerequisites
* Install the MAT Detect plug-in for Zowe CLI From Packages
* Install the MAT Detect plug-in for Zowe CLI From Source
* Validate the Installation
* Create a User Profile
* Create a z/OSMF Profile
* Create a PMA Profile
* Use Cases and Commands
* GET
* perf | pf
* alert | at
* alert-by-job | abyj
* SCOPE
* inc-job | incj
* exl-pgm | exlp
* del-job | delj
* del-pgm | delp
* get-listj | getlj
* get-listp | getlp
* Uninstall the MAT Detect Plug-in for Zowe CLI

Installation

You can install the MAT Detect plug-in for Zowe CLI:
* From the Zowe Package
* From Source

Prerequisites

Before starting the installation of the MAT Detect plug-in for Zowe CLI, verify that you have:
* Zowe CLI installed.
* Zosmf profile created.
* The Performance Management Assistant component (PMA) of MAT is installed and completely customized on your system.

Install the MAT Detect Plug-in for Zowe CLI From Packages

Issue the following command:
``
$ zowe plugins install @broadcom/mat-detect-for-zowe-cli
`
Note:
The latest npm tag installs a version of the product that is intended for public consumption. You can use different npm tags to install other versions of the product. For example, you can install with the @beta tag to try new features that have not been fully validated. For more information about tag usage, see NPM Tag Names.

Install the MAT Detect Plug-in for Zowe CLI From Source

To install the MAT Detect plug-in for Zowe CLI from source, issue the following commands in your command line.

Follow these steps:
1. Clone this repository to the MAT Detect plug-in for Zowe CLI folder on your PC:
`
$ git clone https://github.gwd.broadcom.net/MFD/mat-detect-for-zowe-cli.git
`

2. Navigate to the MAT Detect plug-in for Zowe CLI folder with the cloned source code.
`
$ cd mat-detect-for-zowe-cli
`
3. Install dependencies:
`
$ npm install
`
4. Build the plug-in:
`sh
$ npm run build
`
5. Navigate one step up in the folder hierarchy:
`sh
$ cd ..
`
6. Install the plug-in:
`sh
$ zowe plugins install /path/to/mat-detect-for-zowe-cli
`
In Windows command line:
`sh
$ zowe plugins install ./mat-detect-for-zowe-cli
`

Validate the Installation


To validate the installation, issue the following command:
`
$ zowe plugins validate @broadcom/mat-detect-for-zowe-cli
`
Successful validation of the plug-in returns the response "This plugin was successfully validated. Enjoy the plugin."

Create a PMA Profile

To enable the interaction of the MAT Detect plug-in for Zowe CLI with PMA, you need to create z/OSMF and PMA profiles. The details of the PMA profile are stored in the Zowe configuration file. To create PMA profile, complete the following steps:

1. To create a global Zowe configuration file, use the command zowe config init --global-config. The z/OSMF profile details are created automatically.
2. Specify the host, username, and password. Your credentials are automatically encripted and stored.
3. To create PMA profile, open the created zowe.config json file and add a section with the PMA profile details:
`
"pma": {
"type": "pma",
"properties": {
"job_acct": "123456789",
"job_class": "A",
"job_mclass": "A",
"job_load": "PMA.MAT12.CEETLOAD",
"job_pmahlq": "PMA.MAT12"
},
"secure": []
},
`

PMA Profile Options
--job_acct | --ja (string)
Specifies z/OS TSO/E accounting information. Only numbers are allowed.

--job_class | --jc (string)
Your z/OS class information. Valid values are any characters from A to Z and any numbers from 0 to 9.

--job_mclass | --jmc (string)
Specifies the MSGCLASS parameter value and assigns the job log to the specified output class. The specified MSGCLASS value is used in all JCLs that PMA runs while you execute the commands. If you do not provide the job_mclass parameter, the default MSGCLASS value is used. Values: alphanumeric characters (A-Z, 0-9).
Default value: A

--job_load | --jl (string)
Specifies PMA loadlib information. To provide the correct loadlib name, refer to your PMA installation details (&HLQ.CEETLOAD).

--job_pmahlq | --jph (string)
Specifies the PMA HLQ to access the KSDSALT, KSDSJOB, and KSDSEXC vsam files that ensure the collection of the necessary data.

If the details are not specified or if you want to temporarily use different profile settings, you can specify all or some profile details with each command. The profile details that are provided with a command have the highest priority and override all other values. For more information about using profiles in Zowe, see Using Global Profile Configuration in the Zowe documentation.




Use Cases and Commands

The MAT Detect plug-in for Zowe CLI commands are organized in the following command groups:

GET

The commands from the GET group enable you to get performance information using PMA utilities. You can get the current performance data of your jobs and check for today's performance alerts.

$3

Usage
`
$ zowe mat-pma-util get
`
where command is one of the commands described below.


#### perf | pf
Gets the current performance data of a specific job using PMA. If the current measurement results for any of the measured parameters are higher than the averages, an alert message is displayed.

Usage
`
$ zowe mat-pma-util get perf [options]
`
jobname (string)
The name of the job you are interested in or under test (e.g. TESTPMA8).

Options
The PMA Connection and Profile Options are available for this command.

Examples
- Get the current performance data of the TESTPMA8 job using the default profile:
`
$ zowe mat-pma-util get perf TESTPMA8
`

- Get the current performance data of the TESTPMA8 job using specific PMA profile details:
`
$ zowe mat-pma-util get perf TESTPMA8 --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### alert | at
Check for alerts created in PMA and detect whether any of your jobs violates statistical norms of today’s performance. If the threshold is exceeded, a PMA alert is triggered. This command is recommended for including into developers’ end-of-day build, so that they can get all the jobs that might cause a performance degradation from each day change.

Usage
`
$ zowe mat-pma-util get alert [options]
`
Options
The PMA Connection and Profile Options are available for this command.

Examples
- Check whether any of your jobs violates today's statistical norms of daily performance using the default profile:
`
$ zowe mat-pma-util get alert
`

- Check whether any of your jobs violates today's statistical norms of daily performance using specific PMA profile details:
`
$ zowe mat-pma-util get alert --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### alert-by-job | abyj
Check whether the specific job has violated statistically normal today’s performance. No record returned indicates that no performance degradation has been detected for this job.

Usage
`
$ zowe mat-pma-util get alert-by-job [options]
`
jobname (string)
The name of the job you are interested in or under test (e.g. TESTPMA8).

Options
The PMA Connection and Profile Options are available for this command.

Examples
- Check whether your job TESTPMA8 violates today's statistical norms of daily performance using the default profile:
`
$ zowe mat-pma-util get alert-by-job TESTPMA8
`

- Check whether your job TESTPMA8 violates today's statistical norms of daily performance using specific PMA profile details:
`
$ zowe mat-pma-util get alert-by-job TESTPMA8 --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`




SCOPE

The commands from the SCOPE group enable you to create, update, and view lists of jobs that you want to include in the PAM scope, and lists of programs to be excluded from the PMA scope of work.

$3

Usage
`
$ zowe mat-pma-util scope
`
where command is one of the commands described below.


#### inc-job | incj
Include a job in the PMA scope of work.

Usage
`
$ zowe mat-pma-util scope inc-job [options]
`
jobname (string)
The name of the job that you want to add to the list of inclusions in the PMA scope (e.g. TESTPMA8).

Options
--stepname | --st (string)
The name of the job step that you want to include to the PMA scope.

--procstep | --ps (string)
The procname of the job that you want to include in the PMA scope.

--description | --dc (string)
The description of the job that you want to include in the PMA scope.

The PMA Connection and Profile Options are also available for this command.

Examples
- Include the TESTPMA8 job in the PMA scope:
`
$ zowe mat-pma-util scope inc-job TESTPMA8
`

- Include the specific procname and step name of the TESTPMA8 job in the PMA scope and add a description to the included job:
`
$ zowe mat-pma-util scope inc-job TESTPMA8 --ps TESTCALL --st TESTDO --dc "INCLUDE IN THE CURRENT SCOPE"
`

- Include the specific procname and step name of the TESTPMA8 job in the PMA scope and add a description to the included job using specific PMA profile details:
`
$ zowe mat-pma-util scope inc-job TESTPMA8 --ps TESTCALL --st TESTDO --dc "INCLUDE IN THE CURRENT SCOPE" --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### exl-pgm | exlp
Exclude a program from the PMA scope of work.

Usage
`
$ zowe mat-pma-util scope exl-pgm [options]
`
pgmname (string)
The name of the program that you want to add to the list of exclusions from the PMA scope (e.g. TESTPMA8).

Options
--description | --dc (string)
The description of the program that you want to exclude from the PMA scope.

The PMA Connection and Profile Options are also available for this command.

Examples
- Exclude the TESTPMA8 program from the PMA scope:
`
$ zowe mat-pma-util scope exl-pgm TESTPMA8
`

- Exclude the TESTPMA8 program from the PMA scope and add a description to the excluded program:
`
$ zowe mat-pma-util scope exl-pgm TESTPMA8 --dc "EXCLUDE FROM THE CURRENT SCOPE"
`

- Exclude the TESTPMA8 program from the PMA scope and add a description to the excluded program using specific PMA profile details:
`
$ zowe mat-pma-util scope exl-pgm TESTPMA8 --dc "EXCLUDE FROM THE CURRENT SCOPE" --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### del-job | delj
Delete a job from the list of inclusions in the PMA scope.

Usage
`
$ zowe mat-pma-util scope del-job [options]
`
jobname (string)
The name of the job that you want to delete from the list of inclusions in the PMA scope (e.g. TESTPMA8).

Options
--stepname | --st (string)
The name of the job step that you want to delete from the list of inclusions in the PMA scope.

--procstep | --ps (string)
The procname of the job that you want to delete from the list of inclusions in the PMA scope.

The PMA Connection and Profile Options are also available for this command.

Examples
- Delete the TESTPMA8 job from the list of inclusions in the PMA scope:
`
$ zowe mat-pma-util scope del-job TESTPMA8
`

- Delete the specific procname and step name of the TESTPMA8 job from the list of inclusions in the PMA scope:
`
$ zowe mat-pma-util scope del-job TESTPMA8 --ps TESTCALL --st TESTDO
`

- Delete the specific procname and step name of the TESTPMA8 job from the list of inclusions in the PMA scope using specific PMA profile details:
`
$ zowe mat-pma-util scope del-job TESTPMA8 --ps TESTCALL --st TESTDO --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### del-pgm | delp
Delete a program from the list of exclusions from the PMA scope.

Usage
`
$ zowe mat-pma-util scope del-pgm [options]
`
pgmname (string)
The name of the program that you want to delete from the list of exclusions from the PMA scope (e.g. TESTPMA8).

Options
The PMA Connection and Profile Options are available for this command.

Examples
- Delete the TESTPMA8 program from the exclusions list from the PMA scope:
`
$ zowe mat-pma-util scope del-pgm TESTPMA8
`

- Delete the TESTPMA8 program from the exclusions list from the PMA scope using specific PMA profile details:
`
$ zowe mat-pma-util scope del-pgm TESTPMA8 --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### get-listj | getlj
Get the list of jobs included in the PMA scope.

Usage
`
$ zowe mat-pma-util scope get-listj [options]
`
Options
The PMA Connection and Profile Options are available for this command.

Examples
- Get the list of jobs included in the PMA scope:
`
$ zowe mat-pma-util scope get-listj
`

- Get the list of jobs included in the PMA scope using specific PMA profile details:
`
$ zowe mat-pma-util scope get-listj --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`


#### get-listp | getlp
Get the list of programs excluded from the PMA scope.

Usage
`
$ zowe mat-pma-util scope get-listp [options]
`
Options
The PMA Connection and Profile Options are available for this command.

Examples
- Get the list of programs excluded from the PMA scope:
`
$ zowe mat-pma-util scope get-listp
`

- Get the list of programs excluded from the PMA scope using specific PMA profile details:
`
$ zowe mat-pma-util scope get-listp --ja 123456789 --jc A --jmc A --jl HLQ.CEETLOAD --jph PMAHLQ
`

For any group and command, help is available with --h argument, for example:
`
$ zowe pma get perf –h
`
`
$ zowe pma scope --h
`


Uninstall the MAT Detect Plug-in for Zowe CLI


To uninstall the MAT Detect plug-in for Zowe CLI, issue the following command:
`
$ zowe plugins uninstall @broadcom/mat-detect-for-zowe-cli
``