zAdviser Administration

BMC AMI zAdviser Enterprise On-Prem leverages machine learning to continuously measure and improve an organization’s mainframe DevOps processes and development outcomes. Based on key performance indicators (KPIs), zAdviser measures software development and delivery quality, velocity, and efficiency, empowering enterprise IT leaders to make evidence-based decisions in support of their continuous improvement efforts.

zAdviser Administration is an interactive guide that helps in configuring data streams for zAdviser Enterprise On-Prem.

zAdviser Enterprise On-Prem. records are collected and written to SMF, and these records are then transferred to BMC in one of five ways. The Administration guide helps in configuring the record transfer method that works for your organization, including the JCL Configuration required.

zAdviser Enterprise On-Prem ADMINISTRATION LOGIN

GitHub configurations for DORA metrics

To enable zAdviser to collect and analyze DORA metrics from your GitHub repositories, configure the Git integration as follows:

In the zAdviser Enterprise administration pane, expand Git.

Enter the following details:

Field	Description
Release Branch Prefix	The prefix of your release branches. For example, if your release branch is named release/v1.0.0, enter release.
Secret	A secret key used to verify incoming webhook requests. This ensures only trusted sources (example, GitHub) can trigger events. When configuring multiple repositories, use the same secret key across all repositories.
GitHub API URL	The GitHub API URL. For example, https://api.github.com.
GitHub Access Token	A personal access token (PAT) used to authenticate with GitHub APIs.
Issue Labels	Provides a list of labels that will be assigned to issues.
GitHub Version	Used for choosing supported APIs according to your GitHub plan.

Click Apply to save the configuration.

Configure GitHub webhook to push data to zAdviser

To enable automated data collection for DORA metrics and activity tracking, configure a GitHub webhook to push repository data to zAdviser. The following are the steps to set up a GitHub webhook so that your repository activity is streamed to zAdviser.

Step1: Navigate to your repository settings and add a new webhook

In GitHub, go to Settings for the repository you want to connect.
Under Code and Automation, click Webhooks.
Click Add new and configure the following settings:
Field Value
Payload URL https://{zAdviserHost}/github/webhook
Content type application/json
Secret Generate a secure secret string (see below)

Field	Value
Payload URL	https://{zAdviserHost}/github/webhook
Content type	application/json
Secret	Generate a secure secret string (see below)

Step 2: Generate a secret
It is recommended to use at least 32 characters, preferably 64+ hexadecimal characters.

On Windows (PowerShell):

[System.BitConverter]::ToString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).Replace("-", "").ToLower()

On Linux:

openssl rand -hex 32

Copy the generated secret into the Secret field in GitHub.

Step 3: Select events to trigger the webhook

Under Which events would you like to trigger this webhook?, select, Let me select individual events.
Enable the following events:
- Deployments
- Deployment statuses
- Issues
- Pull requests
- Pull request reviews
- Pushes
- Workflow runs

Step 4: Activate the Webhook

Ensure the webhook is active.
Save the configuration.

Step 5: Verification

After the webhook is created, GitHub will begin streaming data to zAdviser automatically. You can check webhook activity in Recent Deliveries within the Webhooks settings to confirm that events are being received.

Troubleshooting Data Collection Checklist

This section provides a checklist to help you collect diagnostic information, and a list of known issues with suggested workarounds for common problems encountered during setup or usage.

Data Collection Checklist

The following checklist outlines the key files, logs, and system details to collect when troubleshooting zAdviser Enterprise On-Prem.

Item	Description	How to Locate and Collect
Installation logs	Logs generated during the installation process.	Capture any errors displayed during installation. Check the terminal or log files in the installation directory.
zAdviser logs	Application runtime logs.	Zip and download the logs folder located in the installation directory.
Docker container logs	Logs from the key containers (Elastic, Kibana, and zAdviser) that support the application.	Run: docker logs zadviser-elastic docker logs zadviser-kibana docker logs zadviser
Docker runtime details	Status of running containers and image metadata.	Run for docker container details: docker ps -a Run for docker image details: docker images
Configuration files	Application specific config files.	Zip and download the zAdviserConfig folder from the installation directory.
Browser console logs or UI errors	Logs or errors from the browser while using the UI.	Use Browser DevTools → Console tab → right-click and save logs or take a screenshot.
Error screenshots or messages	Screenshots of CLI or UI issues.	Take and attach clear screenshots showing the error messages.
System Information	Details about the host system environment such as opertaing system version, CPU usage, memory allocation, and available disk space.	Run the following command or use tools like lshw, neofetch, or systeminfo (Windows). uname -a, top, df -h
Network Configuration	Network configuration details including DNS settings, proxy configurations, and firewall rules.	Run the following command and check relevant firewall or proxy settings: ifconfig or ip a, netstat -rn, nslookup
Port availability	Make sure that no firewall or security rule is preventing access to the required ports.	Run netstat -tuln, ss -tuln, or telnet <host> <port> to check whether the necessary ports are active and accessible.

Known issues and suggested fixes

The following table lists commonly encountered issues in zAdviser Enterprise On-Prem and provides recommended solutions or workarounds to help resolve them efficiently.

Issue	Description	Workaround
Kibana dashboard fails to load after configuration	After completing the configuration, the Kibana dashboard does not load or display as expected.	Review the configuration file for errors, correct any misconfigurations, and restart the Kibana container.
ITSM / SCM / Usage file upload fails	You may encounter intermittent failures when uploading ITSM, SCM, or usage files through the admin portal because of incorrect file permissions or incomplete container restarts.	Verify file and folder permissions to confirm they are accessible to the container. If uploads continue to fail, restart the relevant zAdviser containers to clear any temporary issues.
LPAR mapping errors	After configuring zAdviser Enterprise, the system may prevent adding or updating LPAR mappings in the admin interface, returning a mapping already exists message even when the configuration appears valid.	To resolve this issue, stop and restart the zAdviser container. This clears any session or state inconsistencies that may prevent LPAR mapping updates.
High resource usage on shared VMs	When zAdviser is deployed on a virtual machine (VM) shared with other applications or services, performance issues may occur due to uncontrolled resource consumption by zAdviser containers.	Limit the CPU and memory usage of zAdviser containers by setting fixed resource caps in the Docker configuration. This ensures stable performance and prevents resource contention with other services running on the same VM.

Manual SMF data extraction and upload process

This section provides instructions for administrators on how to manually extract and upload SMF data to zAdviser. This process is required in the following scenarios:

There has been an interruption in streaming data to zAdviser and backfilling is necessary.
You are installing zAdviser for the first time and want to pre-fill the system with 30–90 days of historical SMF data.

The following are the steps to manually add data to zAdviser:

Step 1: Extract and Convert SMF Data to CSV

Use the following JCL to extract SMF records from the mainframe and convert them into a CSV file

//Specify a Valid Job Card
//*
//* DUMP ZADVISER SMF RECORDS (NON-LOGSTREAM)
//*
//STEP1    EXEC PGM=IFASMFDP
//SMFIN    DD   DISP=SHR,DSN=SMF.DATASET
//OUTDD1   DD   DISP=(,PASS),DSN=&&SMFOUT,
//         UNIT=VIO,SPACE=(CYL,(30,30),RLSE),
//         DCB=(RECFM=VBS,LRECL=32760,BLKSIZE=4096)
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
INDD(SMFIN,OPTIONS(DUMP))
DATE(START,END)         <--- Specify the Start and End dates for the SMF Extract (Format: YYYYDDD)
OUTDD(OUTDD1,TYPE(###)) <--- Replace ### with the SMF record number specified in the LMCLxx member for SMF_ID
//*
//* CONVERT TO .CSV
//*
//STEP2    EXEC PGM=ROICOPY
//STEPLIB DD   DISP=SHR,DSN=BMC.AMI.DEVX.ECC.LOADLIB
//         DD   DISP=SHR,DSN=BMC.AMI.DEVX.ECC.AUTHORIZED.LOADLIB
//ROIIN    DD   DISP=(MOD,PASS),DSN=&&SMFOUT
//SYSUDUMP DD   DUMMY
//CSVOUT   DD   DSN=ZADVISER.ROICOPY.CSV, <--- Update the name of the file that you will be creating.
//         DISP=(NEW,CATLG,DELETE),
//         EATTR=OPT,VOL=SER=SYSDA,
//         UNIT=SYSDA,SPACE=(CYL,(25,25),RLSE),
//         DCB=(DSORG=PS,LRECL=1184,RECFM=U,BLKSIZE=32760)

Step 2: Download the CSV file

Transfer the ZADVISER.ROICOPY.CSV dataset to your local machine.
Make sure the file is downloaded in ASCII format.

Step 3: Upload the file to zAdviser

Log in to the zAdviser Administration page.
Navigate to the Manual Upload section.
Select and upload the ASCII CSV file.

Step 4:Data Ingestion

The uploaded file will be ingested into zAdviser automatically as part of the scheduled ingestion process. You can monitor the ingestion status from the Admin dashboard.

Uploading SCM, ITSM, and Product Usage Data to zAdviser

You can upload the SCM, ITSM, and Product Usage data to be ingested into zAdviser by selecting the appropriate category and sub-category (if applicable) and following the provided guidelines.

Supported categories and file formats

Category	Sub-category	Accepted File Format(s)
SCM	Changeman, Endevour	CSV, TXT
ITSM	Jira	CSV
Product Usage	None	CSV

Upload limitations

File Quantity: A maximum of 5 files can be uploaded at once.
File Size: Each file must not exceed 100 MB in size.

Handling larger files

If files exceed the upload limits (either in quantity or size), you can transfer them using SCP to the specified path displayed on the right-hand pane after selecting your category and sub-category.

Type your

Browser Session: Keep your browser open throughout the upload process to monitor the progress of each file in real-time.
Category Selection: You can select only one category and its corresponding sub-category at a time for file uploads.

Processing and confirmation

After successfully uploading the ITSM and SCM files, processing will begin within the next hour. Upon successful completion, you will receive an email confirmation (if email notifications are configured). You can then view updates on the respective dashboards in Kibana.