IBM Fault Analyzer for z/OS® Beta
The IBM Fault Analyzer for z/OS® VS Code extension works in conjunction with the Zowe Explorer VS Code extension.
IBM Fault Analyzer for z/OS® helps developers analyze and fix application and system failures.
When applications abnormally end (ABEND) it is crucial to understand the root-cause.
IBM Fault Analyzer for z/OS® can discover ABENDs faster, more confidently, and in less time
by automatically harvesting real-time information of the ABEND and its environment at the time of failure.
General requirements
- Assumes knowledge of IBM Fault Analyzer for z/OS® product installation and features
- The Fault Analyzer VS Code extension connectivity to the Fault 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 Application Delivery Foundation for z/OS® common component server
- ADFzCC must use the AT-TLS feature when configuring TLS support
VS Code extension requirements
- VS Code
1.90.0+
- Zowe Explorer
2.17.0+
- Assumes that the user has knowledge of the Zowe Explorer extension before using the IBM Fault Analyzer extension
Optional VS Code extensions
- IBM Z® Open Editor
- Provides color coded sources when viewing side files in fault reports
- Provides color coded job spool data sets
Beta host requirements
Beta limitations
- Does not support all platforms that Zowe Explorer supports:
- ✅ Windows
- ❌ Linux (untested)
- ❌ macOS (untested)
- Does not support all Integrated Development Environments:
- ✅ VS Code
- ❌ Eclipse Theia (untested)
- ❌ Eclipse Che (untested)
- ❌ Red Hat CodeReady Workspaces (untested)
- Does not support Multi-Factor Authentication (MFA)
- Does not ask to trust self-signed certificates when connecting to the ADFz common component server
Beta features
This is a beta version of the IBM Fault Analyzer extension and does not support the full
functionality of the ISPF Fault Analyzer client, or of the Eclipse Fault Analyzer client.
Itemized below are the features supported and not supported in broad terms.
History files
- Open history files in a separate view
- Add history files to the Fault Analyzer tree view:
- From the Zowe Data Sets tree view
- From the Fault Analyzer tree view
- From the Command Palette
- Remove history files from the Fault Analyzer tree view
Fault reports
- Reanalyze and show fault reports in a separate view:
- From the history file view's context menu, or by clicking on a fault entry reference
- From a job's context menu in the Zowe Jobs tree view
- From a job's JESMSGLG editor as hyperlinks, and from the context menu
- From the Command Palette
- Navigate to sections of the report:
- Event Detail hyperlinks to jump to a specific event
- Source code hyperlinks to open a source file at a specific line
ADFz Common Component server connections
- Associate an ADFz port with a Zowe Profile
- Remove the association between an ADFz port and a Zowe profile
Unsupported features
History files
- Add default and recent history files
- Copy/Rename/Remove fault entries from the history file
- Filter fault entries
- Choose column ordering and visibility
- View fault entry properties
Fault reports
- Side files:
- IDITrace logs
- JCL for the job causing the ABEND
- Minidump
- Hyperlinks:
- Lookup view links for viewing ABEND explanations
- Data Set links
- Memory links jumping to minidump
- CICS links
Views
- Add view
- Create view
- Show and navigate views
Fault analytics
- Manage and display charts
Getting started
Specifying the ADFz connection port
Before you begin, all the above requirements must be fulfilled.
- Open VS Code
- If necessary, create at least one Zowe profile: team configuration profile or v1 profile (deprecated)
- Switch to the Zowe Explorer toolwindow
- Right-click on the profile that matches the z/OS subsystem your ADFz common component server is running on
- From the Application Delivery Foundation for z/OS menu item, choose Configure ADFz port
- Enter the port that your ADFz common component server is configured to use
You are now ready to use the IBM Fault Analyzer VS Code extension.
NOTE: if you access a Fault Analyzer feature before configuring the port number,
you will be prompted to specify the port the first time only.
The Fault Analyzer tree
When the Zowe Explorer toolwindow is selected in VS Code, the toolwindow has three tree views by default:
Data Sets, Unix System Services, and Jobs.
The Fault Analyzer extension adds a Fault Analyzer tree view as well to manage the history files that have been added.
When an ADFz common component server port is associated with a profile, that connection will be displayed in the Fault
Analyzer tree view.
Tree structure
Connection nodes
There will be one root node representing each host and port of an ADFz common component server connection.
Browse History Files nodes
These are the parent nodes of any history file that have been added for the connection.
- The Add history file inline button (or context menu item) prompts for a data set name
for a new history file to open and add to the tree
History file nodes
These are nodes representing a history file that has already been added.
- The Open history file inline button (or context menu item) opens the history file or reveals it if already open
- The Remove history file inline button (or context menu item) removes the history file from the Fault Analyzer tree
Adding history files from Zowe Explorer's Data Sets tree
History Files can also be added from Zowe Explorer's Data Sets tree:
- From a profile in Zowe Explorer's Data Sets tree, select its Search Data Sets inline button or context menu item
- Select an existing filter or create a new filter that will show the history file that you want to open and add to the
Fault Analyzer tree
- From the context menu, select Fault Analyzer > Add history file
- If an ADFz common component server port has not already been specified for this profile, the port will be prompted for
and a new ADFz connection will be created in the Fault Analyzer tree
- The history file will be added to the Fault Analyzer tree if it does not already exist in the tree, and will be
opened in a new tab
Viewing fault reports from a history file
Once a history file has been added to the Fault Analyzer tree, it can be displayed by clicking on it in the tree.
Once the history file is displayed, you can open a fault report by double-clicking on a fault entry row.
An additional path to achieve the same result is to open the context menu over a fault entry row, and select Reanalyze.
Viewing fault reports from Zowe Explorer's Jobs tree
When jobs that have generated one or more ABEND are viewed from Zowe Explorer's Jobs tree,
you will be able to view the fault report in multiple ways.
From the Jobs tree node
Right-click on the job that completed with an ABEND
Select Fault Analyzer > Open fault report
NOTE: if there is more than one ABEND in the job, you will be prompted
to select which fault report you want to open
From a job's JESMSGLG output data set (hyperlinks)
- Expand the tree node for the job that completed with an ABEND
- Click on the JES2:JESMSGLG output data set to open it
- Hyperlinks will be displayed for each ABEND that occurred.
Ctrl-clicking a hyperlink will open the fault report associated with the ABEND
- Expand the tree node for the job that completed with an ABEND
- Click on the JES2:JESMSGLG output data set to open it
- Open the editor's context menu and select Open fault report
Fault Analyzer VS Code commands
The Fault Analyzer extension adds new commands to the VS Code Command Palette.
Add history file
Adds a history file to the Fault Analyzer tree in the Zowe Explorer toolwindow.
You will be prompted for:
- An ADFz common component server connection if there is more than one connection defined
- A data set name for the history file you want to open and add to the Fault Analyzer tree
Open fault report
Performs reanalysis on a fault report and opens that report.
You will be prompted for:
- An ADFz common component server connection if there is more than one connection defined
- The data set name for the history file containing the fault entry you want to reanalyze and open
- The fault entry ID for the report you want to reanalyze and open
Overview of the Fault Report view
The Fault Report view is a collection of tabs that enable the user to view different sections of the report.
Some sections have hyperlinks that will open source files at a specific line number.
The Event Details section displays event hyperlinks to jump to the definition of the event in another section.
The layout is similar to the Fault Reports view in the IBM Fault Analyzer Eclipse client.
