IBM Application Performance Analyzer for z/OS®

Provides support for IBM Application Performance Analyzer functionalities in VS Code

The IBM Application Performance Analyzer for z/OS® VS Code extension works in conjunction with the Zowe Explorer VS Code extension. IBM Application Performance Analyzer for z/OS® helps developers analyze application performance and resource usage. IBM Application Performance Analyzer for z/OS® can identify hot spots in application code and spikes in resource usage by taking real-time samples of z/OS applications. APA’s unique architecture means that there is very little additional overhead incurred when taking these measurements.

General requirements

• Assumes knowledge of IBM Application Performance Analyzer for z/OS® product installation and features
• The Application Performance Analyzer VS Code extension connectivity to the Application Performance Analyzer host is similar to using the Application Delivery Foundation for z/OS® Common Component (ADFzCC) server
  • Assumes knowledge of how to install and configure the ADFz Common Component server
  • ADFz Common Component must use the AT-TLS feature when configuring TLS support

VS Code extension requirements

• VS Code 1.90.0+
• Zowe Explorer 3.1.0+
• PDF Viewer 0.1.6+
  • Assumes that the user has knowledge of the Zowe Explorer extension before using the IBM Application Performance Analyzer extension

Host requirements

• IBM Application Performance Analyzer for z/OS® 16.1.2+
• IBM Application Delivery Foundation for z/OS® Common Components 1.10.0+
  • There must be at least one ADFz Common Component server configured and deployed on the host that you want to work with

Note that while the 16.1.0 host build might work for some features, it is not officially supported.

Supported charsets

The extension supports resources in both English (IBM1047).

Features

The current version of the IBM Application Performance Analyzer extension does not support the full functionality of the ISPF Application Performance Analyzer client, or of the Eclipse Application Performance Analyzer client.

Itemized below are the features supported and not supported in broad terms.

APA Observation List

• View a list of observations associated with an APA server (better term here?) in a separate web view.
• Delete one or more observations from the observation list.
• Refresh the list to pick up any changes from the APA server.
• Select an observation to view an observation summary or view a list of available detailed reports.

APA New Measurement Request

• Create a new APA measurement request and submit it to APA on z/OS in a separate web view.
• Save a newly created APA measurement request to local disk for retrieval later.
• Read a previously saved APA measurement request from local disk and submit it to APA on z/OS.

APA Measurement Reports

• Select and download APA measurement reports to local disk.
• View APA measurements within VS code within a separated edit view.

TLS Support

• The extension supports TLS communication with ADFz Common Components server.
  • It will automatically detect if the server expects a TLS connection.
  • Currently only a TLS connection implemented with AT-TLS is supported.

Unsupported features

• Trust manager for certificates used when connecting to the ADFz Common Component server
• Multi factor authentication (MFA)
• Source program mapping (under development)
• Direct request for XML and JSON report downloads. This is supported indirectly using CAZBATCH and the Zowe job submission facility.
• Report A02 – Request printed reports. This is supported indirectly using CAZBATCH and the Zowe job submission facility.
• Import and export of measurement files.
• z/OS System SSL is not supported for the connection between client and z/OS (under development). However, as noted earlier, AT-TLS connections are supported.

Getting started

Configuring the ADFz Common Component connection

Before you begin, all the above requirements must be fulfilled.

1. Open VS Code
2. If necessary, create at least one Zowe profile: team configuration profile or edit your existing profile.

3. Ensure that the Zowe profile contains a base entry that specifies the common host name and the securely stored z/OS user and password. You can set the base properties user and password from the command line with the command zowe config secure --gc

4. In the same Zowe profile, add a new entry specific for the APA connection. The type property must be “apa”. Include the port number for this connection where the ADFz server is running.

5. If you wish to store downloaded reports in a specific folder, include the report_download_folder property. Otherwise downloaded reports are saved in the VS code project folder.
6. If the port implements TLS with AT-TLS, set the ca_file property to point to a local file containing one or more CA root certificates. At least one of those CA certs must be the one that was used to sign the the ADFz server certificate. Multiple CA certificates can be concatenated in the same file. The certificates should be stored in base64 format. (-----BEGIN CERTIFICATE----- / -----END CERTIFICATE----- format).
7. If you wish to ignore hostname authentication, for example if you don’t have the proper CA certificate or if the CA is self signed, set rejectUnauthorized to false (as is the case here.) If rejectUnauthorized is set to true, then the extension will attempt to verify the server certificate against the list of supplied CA certificates.

You are now ready to use the IBM Application Performance Analyzer VS Code extension.

The Application Performance Analyzer tree

When the Zowe Explorer tool window is selected in VS Code, the tool window has three tree views by default: Data Sets, Unix System Services, and Jobs.

The Application Performance Analyzer extension adds an Application Performance Analyzer tree view as well to manage connections to an ADFz server hosting an APA plugin. When an ADFz common component server port is associated with a profile, that connection will be displayed in the Application Performance Analyzer tree view.

Warning Sometimes the available APA connections are not listed below the APPLICATION PERFORMANCE ANALYZER heading. If this happens, click the refresh icon to the right (circling arrow). This should update the display with the current connection definitions.

Tree structure

Connection Nodes

There will be one root node representing each host and port of an ADFz common component server connection. Following the connection icon, the IP and port of the corresponding z/OS host will be displayed in a connection string. If the connection is active, the icon will be green. If in a disconnected state, the icon is displayed in red.

If you hover over the APA connection node (most systems will only have one connection node, though multiple connections are supported) or select it with a mouse click, a “Connect to Host” icon and a “Disconnect from Host” icon will be displayed. The connect icon appears first in the row as a single plug. The disconnect icon appears as a plug and socket combination being unplugged. Click on the appropriate icon to connect or disconnect.

APA Started Task (Server) nodes

After a successful connection (green icon), you can expand the connection node to display the APA Started Task nodes. Under each connection node, there will be one or more APA server nodes, one for each instance of APA started task running on that system.

At the far right of the row containing an APA server node, there are two icons. The first icon is in the shape of a lightbulb, and represents a create new measurement request. The second icon is in the shape of a numbered list and represents an APA List Measurements request.

Create New Measurement Webview

Click the create new measurement icon (lightbulb) and the Create New Measurement Webview opens. The left pane of the Create New Measurement webview contains a navigation panel for all the available fields. The right pane of the Create New Measurement webview contains the input boxes for each new measurement field.

At the top of the right pane, there are three action buttons:

Submit New APA Measurement Request

This action will collect the data entered in all of the input boxes and create a new measurement request on the APA server.

Import Measurement Request from Local File

This action will read a previously exported measurement request into the appropriate input boxes in the webview.

Export Measurement Request to Local File

This action will save all the data entered in all of the input boxes in the local file system for later use.

List Measurements Webview

Click the APA List Measurements icon (rendered as a numbered list) and the List Measurements Webview opens. It displays the same columns as the APA ISPF list of measurements in report R02.

In addition, there is also a “Line Action” column that contains icons to perform actions on the selected measurement. These icons are on the far-left side of each row. There are currently three actions that can be performed. The +/- icon will expand/collapse a nested observation with multiple child observations. The expanded child measurements are outlined in blue.

The clipboard icon will display the measurement details or observation summary

The bullet point list icon will display the APA Available Reports List webview for this measurement. From this list, you can select the reports that wish to view.

There is also a “Delete” column on the far-right side of each row that contains a red delete action icon to delete the measurement.

Viewing APA Reports

When a user selects a report from the APA Available Report List webview, the extension first checks if this report has already been downloaded and saved in the local folder "report_download_folder" specified in the Zowe profile. If the "report_download_folder" is not set, the APA extension will search the current VS Code project root directory.

If the report is available, it will display it to the right of the Report List webview in a PDF viewer window.

If it is not available, it will download it from the APA server, save it in the appropriate folder, then display it to the right of the Report List webview in a PDF viewer window.

Currently all reports are displayed as PDF documents. The PDF Viewer extension published by Mathematic Inc. ( PDF Viewer - Visual Studio Marketplace ) must be installed to implement this functionality. Multiple reports can be opened, each in their own tab. The tab of each PDF report displays a text string consisting of the APA Report Code, the measurement number and the APA Server Name, all joined together with underscores.