In each column, The Support Authority discusses resources, tools, and other elements of IBM® Technical Support that are available for WebSphere® products, plus techniques and new ideas that can further enhance your IBM support experience.
IBM Support Assistant is a free application that provides features for self-help problem determination and a platform for obtaining diagnostic tools. These features and tools streamline troubleshooting by making it easy to organize, analyze, diagnose, and eventually solve problems that might occur with IBM software or deployed applications.
The new Beta release of IBM Support Assistant 5.0 features many usability improvements over the current version 4.0 client application, and, in addition, has adopted a cloud-based approach. As a server application with a rich, browser-based front end, you can offload the analysis of data to a server class machine and avoid some of the system resource limitations that might be experienced with a typical laptop or desktop system.
A server-based install also enables an administrator to install a single instance of IBM Support Assistant that can then be used by a group of users and accessed very simply by pointing a browser to it where resources, files, information, and tools can be shared.
The intent of this article is to introduce the IBM Support Assistant 5.0 strategy and provide a basic understanding of the tool, its key concepts, and core functions.
Before installing and using IBM Support Assistant 5.0, you must ensure that the target system's hardware, operating system, and browsers that will access IBM Support Assistant meet the minimum requirements.
There are two installation options and each one has two deployment options:
- IBM Installation Manager
IBM Installation Manager is a single installation program that can use a remote repository to install, modify, or update IBM Support Assistant and any available problem determination tools. It determines and shows available packages, checks prerequisites and interdependencies, and installs or modifies the selected packages. You can use an existing IBM Installation Manager instance and configure it to use the IBM Support Assistant repository or you can download and use a pre-configured Installation Manager. Using IBM Installation Manager is the recommended approach since it enables you to easily stay up to date with IBM Support Assistant and each of the individual tools. As new tools are made available, you can easily discover and install them directly from the Installation Manager application. Details on how to use this approach are documented in the Installing IBM Support Assistant 5.0 Team Server Beta 2 Technote.
- All-in-one solution
This solution has everything you need to run the IBM Support Assistant application, including an embedded application server and Java™ runtime. This option is easier to use because it models the "unzip and go" scenario; however, this approach prevents you from being able to easily get updates and selectively install tools. The common use case for this approach is when IBM Installation Manager is not a viable option, such as when deploying to IBM PureApplication System or when corporate policies prevent access to IBM Support Assistant repositories on ibm.com.
How you install and start the application depends on which operating system platform you are targeting. Be aware that IBM Support Assistant 5.0 does not support installation into a directory path that contains '.' characters or space characters. The server-based tools included in the package use the IBM Support Assistant JRE to execute in their own JVM process.
Each of the installation options provides two ways to deploy the IBM Support Assistant application:
- Standalone deployment
The default, recommended deployment is to use a standalone approach where everything that you need to run IBM Support Assistant, including an embedded application server, is provided with default configuration settings in place. With this approach, you can usually start the application immediately after completing installation.
- EAR deployment into an existing WebSphere Application Server
If you have an existing WebSphere Application Server, you can deploy the IBM Support Assistant 5.0 EAR and associated tool WAR files into it. This option is more flexible, because you have more control over how the application and its tools are installed.
The IBM Support Assistant 5.0 EAR is supported on WebSphere Application Server V184.108.40.206 or higher. Using the WebSphere Application Server admin console, you can install the ISA5.ear file just as you would install any other enterprise applications. The fast path install via the administrative console can typically be used. You will also need to install the tool WAR files from the download package as separate web applications. The server-based tools use the WebSphere Application Server JRE to execute in their own JVM process. Quick steps for installing IBM Support Assistant as an enterprise application, including system requirements, are available.
Either option can be installed onto your own desktop machine, as well as on a shared server. Installing onto your desktop is a good option for trying out IBM Support Assistant before deploying out to a team environment, or if you will be using the application as a single-user instance.
Several elements of the IBM Support Assistant 5.0 runtime can be changed from their installation default values. These include location of case files, JVM max heapsize, and port numbers. The ReleaseNotes.txt file, found at the root directory of any of the download archive files, includes this configuration information, along with Quick Start information, known restrictions, and requirements).
Once you have the application installed and any optional configuration
completed, you're ready to get started using the tool. This is easy.
Assuming you're using default values, open a browser to
http://<hostname>:10911/isa5 and try it out!
IBM Support Assistant 5.0 emphasizes problem determination through diagnostic tooling in a multi-user environment. There are several new key features and concepts that are surfaced in the application to support this focus. Many of these features will be highlighted as the tool's components are described through the typical usage scenarios detailed below.
- Case management
Because the Beta 1 release supports a multi-user installation, it is important to logically partition your problem determination investigation such that your files, reports, and other artifacts don't intermingle with another team member's investigation artifacts for a separate problem. It will also be critical to separate your artifacts when you investigate several different problems over a long period of time. This enables your diagnostic input files (as well as tooling output files) to be clearly differentiated. To support efficient organization of related files, IBM Support Assistant supports a basic case concept and provides a Case Management component to help you manage various cases that your team creates within the application.
A case is simply a container for a logical grouping of files and information. A typical practice would be to group artifacts pertaining to a singular issue. For example, if your users are reporting timeouts in a shopping cart application, then you would create a case specifically for diagnosing this reported problem.
To start creating a container for analysis of this problem, open the Case Management panel using the slide out Cases tab in the top-left of the UI (Figure 1) and click the Add button. IBM Support Assistant will automatically assign a unique identifier for the case; you only need to provide a short summary and description of the problem. The Case Management panel is where you'll perform all of the basic management actions to create, delete, and modify cases.
Figure 1. Case Management panel
Once the case information is provided, you can close the tab and set the case context for your session from the case selection drop-down, as shown in Figure 2. When a case is set for your session, you'll be able to see all the files associated with that case and add new files, such as any Java snapshots, configuration files, or other files relevant to the problem.
Figure 2. Case selection
- File management
You'll work with files associated with a case through the Files tab. This is the area where you manage files by performing basic organizational operations against them, such as add, delete, move, and rename. The files that you manage in a case can come from a remote QA, test, or production system, and could have even been gathered in an automated fashion with a data collection utility like IBM Support Assistant Data Collector.
The Files tab is formatted in a familiar file system explorer-like interface. You can easily navigate through folders in a left navigation panel and see the contents of the folder(s) in the details panel. As you might expect, interacting with files to perform actions against them is possible through a context menu similar to an operating system's file explorer, where items in the context menu trigger actions against the items selected in the files table.
- File actions
There are several common actions available that you can invoke against a file, including:
- Download to your local system.
- Compress and Unpack archive files.
- Transfer a file by performing a Move or Copy.
- View the contents of a file directly in the browser.
- Delete a file by using Send to Trash.
IBM Support Assistant also provides file actions that invoke problem determination tools to kick start your diagnosis. To perform analysis of a file or set of files, you would select the Problem Analysis option from the context menu, as shown in Figure 3. To simplify the selection of an appropriate analysis tool, IBM Support Assistant leverages some file association rules to provide a best-attempt match for a tool that should be used against the selected artifact(s). In Figure 3, you can see that a heapdump*.phd file has been selected in the files table and the Memory Analyzer tool is recommended as a tool that is useful in diagnosing heapdumps. There are actually several tools available in this instance and they're all available from the Other... menu option, but IBM Support Assistant has helped narrow down the list of available tools to present the ones that are applicable in a given context.
Figure 3. File actions
New in the Beta 2 release is a capability to automatically analyze your log and configuration files and present candidate knowledge base matches. With this new function, you can instruct IBM Support Assistant to scan all the logs, dumps, and other files within your “cases” to automatically identify potential anomalies, or “symptoms,” that might lead to a solution for this case. The scan also performs an initial search in a custom Knowledge Base to determine if there are any known Technotes or APARs that match the symptoms that have been found.
The starting point for automated analysis is through a set of buttons in the upper right corner of the application. The Scan this Case button will kick off an automated scan and will go through all of the files in the current case, including files nested inside of archive files (zip, jar, tar.gz, and so on). The next button is a status identifier that will let you know whether a case has been scanned successfully or not, if there are new files that need to be rescanned, and so on. Clicking on this button will give you more information about the current scan status. Finally, there is a Global Filter button that can be configured and enabled or disabled. Via the global filter configuration panel, you can select which types of files, date ranges, and other attributes allow you to refine your focus on specific files which meet your criteria.
Figure 4. Scan example
Once a scan has occurred, automated analysis capabilities are surfaced through several different areas of the user interface.
Within the Files view, automated analysis contributes extra metadata to the files grid. You will see information in new columns such as Symptoms, Knowledge Base matches, First and Last Timestamp, and Type. Each of these columns contain information specific to the file in the same row which was acquired by scanning the contents of the file. You now have, at a glance, quick insight into your files without even needing to open them.
Furthermore, if you select a file, you will be presented with a detailed view of the file at the bottom of the page. The Details view will present you with even more information, such as hostnames, server names, process IDs, JVM versions, product versions, fix pack levels and more. There’s a wealth of information pulled from the contents of the files in this view.
Figure 5. Files view
The Overview shows detailed information gathered from a scan across all of the files in a case and presents it in one simplified view. This gives you a quick snapshot of the environment in effect for the log files, dump files, and others when they were created. Any of the properties in the Overview can be clicked to open a details panel showing you a list of all of the files within the case for which that particular value was found.
Figure 6. Overview view
The Symptoms view displays a list of all the potential anomalies or “symptoms” found in the files within the case. These symptoms could be error and warning messages, exceptions, and other recognizable identifiers that could be clues that something isn’t quite right. Each symptom is ranked in order of probable relevance so that you can start at the top of the symptom list to focus on the conditions that are most likely related to an occurring problem. Similar to the Overview and Files view, you can select a symptom to open a details panel to get more information about the symptom. In the details panel, you’ll see additional information, such as the occurrences within files where the symptom was discovered (including exact timestamps and line numbers within files), detailed information about the individual symptom, and knowledge base matches for the symptom.
Figure 7. Symptoms view
The Global Knowledge Base Matches view starts the other way around from the Symptoms view. Here, you will be presented with a list of candidate knowledge (technotes and APARs) which might be applicable to the symptoms discovered when scanning your case. Like the Symptoms view, the candidate knowledge has been ranked so that the most likely hits are pushed toward the top of the list, thereby enabling you to rapidly focus on items that might help resolve a problem quickly. Again in this view, you have the ability to get a detailed view of any selected entry. Select a knowledge base entry in the grid to see details about the match. You’ll be able to see details about the technote or APAR, links to quickly search for additional references, which symptoms were discovered for the applicable knowledge, and information about which files contained the symptoms for the candidate knowledge.
Each of the views and functions related to Automated Analysis are designed to help you perform steps that you would otherwise do in a manual fashion, albeit more rapidly and accurately. For the Beta 2 release, the knowledge base and symptoms that can be recognized is limited to a subset of WebSphere Application Server based products. The IBM Support Assistant team is working with other IBM products to continue to expand the reach of automated analysis to other products and brands within IBM. Periodically, a new knowledge database is made available. For the best possible results, you should always run scans against the most recent version of the Knowledge Database. If a new knowledge database is available, then the dialog presented when invoking a scan will give you an option to download and install the updated knowledge.
In a Support Analyst role, a primary capability that you'll be interested in getting from IBM Support Assistant is access to tools and utilities that aid you in diagnostics so that you can get at the root cause of a symptom you're investigating. As version 5 evolves, it will grow and focus more on its mission as a problem determination tooling platform and the features that support that direction. IBM Support Assistant provides a variety of types of tools and supporting views and functions to simplify tool understanding and invocation.
In the Beta 2 release of IBM Support Assistant 5.0, a limited number of tools are currently available. This inventory of tools will grow over time and will be distributed through the IBM Installation Manager.
There are three key types of tools provided in IBM Support Assistant and each type has its benefits and compromises. In some cases, a tool might function as more than one type to support different use cases and needs.
- Report generator tools
Report generator tools accept one or more files or folders as input, then process the data and generate a simple output file, usually in the form of an HTML or .txt report. Other than providing the initial input files and some optional input parameters, these tools are not interactive. These batch tools are simple to run and have the benefit of consuming no local resources. You invoke them and then can go work on other tasks while waiting for an analysis report to be created.
- Web-based tools
Web-based tools run most of their analysis processing on the IBM Support Assistant server and provide a rich, interactive experience in the UI in the browser. These types of tools are beneficial for activities where you want to offload heavy processing of files to a more powerful server, yet your diagnostic needs demand an interactive experience to perform actions such as drilling into a series of classes.
- Desktop tools
Desktop tools are typical desktop client-side applications that are launched via the IBM Support Assistant browser UI. By leveraging Java WebStart, the entire tool will be installed and run locally on your desktop. This type of tool has a few drawbacks:
- A Java plugin is required for your browser.
- Local system resources are required to run the client tool.
- You must have access to the files you wish to analyze by downloading them from the application, leveraging mapped drives that enable access to the server file system, or installing IBM Support Assistant locally on your desktop such that the tools and the application are running on the same machine.
Using the Tools tab, shown in Figure 8, you can learn about the capabilities and types of analysis that each tool in IBM Support Assistant can perform, as well as find other information you should know prior to running a tool. You can read about tools, launch them and, for report-generating tools, see the execution status. This is a good place to browse and get familiar with tools.
Figure 8. Tools tab view
The Tools tab displays a catalog of available tools in a left navigation pane. At a glance, you can learn a little bit about a tool by interpreting the icons displayed. To learn more, you can select it and view the details of a tool in the right panel. This is where you discover the tool's capabilities and understand important attributes that characterize a tool. From the details pane, you also have access to a toolbar that enables you to launch the tool and get quick access to the tool's documentation for more detailed usage assistance.
One other key feature to note is a search field in the top-right corner. This field enables you to search for information across all of the available tools' documentation to quickly find information or data you might need. Whether you're searching for information about how to use a tool or just want to discover what tools might be applicable to a particular keyword, this field is a quick shortcut to the full Information Center with tooling documentation.
The Reports tab provides a quick, concise view into all of the reports that have been generated from the execution of report-generator analysis tools within the current case. Rather than having to browse through the Files tab to locate a tool's output file, you can skim through the list of generated reports in the left navigation (Figure 9) and even quickly tell if the tool succeeded, when it was run, and what its input files were.
Figure 9. Reports tab view
If there's a report you're interested in reading, selecting the entry will display the report directly in the report panel on the right. Further conveniences are available in the toolbar of the reports view to enable you to quickly navigate to the report's input files or output directory. You can re-run the tool if desired, or open it in a separate browser window or tab if you want more screen real estate to read the report.
Table 1 shows a list of available tools in IBM Support Assistant 5.0.
Table 1. Available tools
|Garbage Collection and Memory Visualizer (GCMV)||IBM Monitoring and Diagnostic Tools for Java - Garbage Collection and Memory Visualizer is a verbose GC data visualizer. It parses and plots J9 and Sovereign verbose GC logs and -Xtgc output. It provides a graphical display of a wide range of verbose GC data values and it handles optthruput, optavgpause, and gencon GC modes. You can select and parse multiple files for comparison.|
|Health Center||A lightweight tool that monitors active IBM Virtual Machines for Java with minimal performance overhead and provides live tuning recommendations and observations.|
|HeapAnalyzer||IBM HeapAnalyzer analyzes Java heap dumps and produces a summary report identifying leak suspects and showing statistics about the heap, such as number of objects, number of references, number of classes, heap size, and so on. It then lets you search and visually inspect the heap with graphical and tabular views.|
|Memory Analyzer||IBM Monitoring and Diagnostic Tools for Java - Memory Analyzer is used to analyze dumps from IBM and Sun Java Virtual Machines to find the causes of various memory problems such as OutOfMemoryErrors.|
|Pattern Modeling and Analysis Tool for Java Garbage Collector (PMAT)||PMAT parses verbose GC traces and performs pattern modeling analysis of Java heap usage. PMAT produces a report to help you tune the Java heap.|
|IBM Portal Log Analyzer||IBM Portal Log Analyzer is designed to aid in troubleshooting by using a ConfigTrace.log from Websphere Portal. After executing the tool, view the generated HTML report file in the output directory.|
|Profile Port Checker||The Profile Port Checker tool scans a collection .jar or .zip file for all server ports. A report is created listing all the server ports that were found along with any duplicate port setting, enabling you to spot potential port conflicts.|
|Thread and Monitor Dump Analyzer (TMDA)||TMDA compares each thread dump and monitor dump and automatically detects hangs, resource contention, Java monitor ownership directional graph structure, and deadlocks.|
|WebSphere Application Server Configuration Visualizer||WebSphere Application Server Configuration Visualizer generates an interactive HTML visualization of a WebSphere Application Server configuration, including Service Integration Buses and databases. It accepts any combination of .zip or .jar files containing configuration directories. Configurations from multiple nodes in a cell will be merged into a single visualization, and multiple cells can be displayed in the output.|
This article presented an overview of the features and functions available in the Beta 2 release of IBM Support Assistant 5.0. These capabilities support a future strategy of delivering a cloud-based architecture for problem determination needs and serve as a solid foundation for the future evolution of troubleshooting tools and services within the IBM software family.
We look forward to providing many new useful functions through future updates to this initial Beta. Feedback on the future strategy and discussion about features (currently available and those desired) is encouraged on the IBM Support Assistant developerWorks forum.
IBM Support Assistant 5.0 Beta home page
IBM Support Assistant (ISA)
Enabling Verbose GC logging in WebSphere Application Server
Enabling dumps in WebSphere Application Server
IBM Support Portal
The Support Authority: If you need help with WebSphere products, there are many ways to get it
IBM Software product
IBM Software Support Web site
IBM Education Assistant
WebSphere Software Accelerated Value Program
Get products and technologies
Video: IBM Support Assistant 5.0 Overview
and CICS Support Blog
Forums and newsgroups
Support Technical Exchange on Facebook
Global WebSphere Community on WebSphere.org
- Follow IBM Support on Twitter!
- WebSphere Electronic Support
- WebSphere Application Server information
- WebSphere Process Server
- WebSphere MQ
- WebSphere Business Process Management
- WebSphere Business Modeler
- WebSphere Adapters
- WebSphere DataPower Appliances
- WebSphere Commerce
- IBM Support Assistant Tools
Jim McVea is a technical architect for the IBM Support Assistant project. He joined IBM in 1998 as a Support Analyst and has worked on various support and serviceability initiatives within IBM through the years. Jim's focus continues to be identifying ways to improve the IBM Support Assistant application and analyzing areas to simplify self-help.