Express (Distributed operating systems), v8.0 > Troubleshoot and support > Analyzing application server Java system dumps with the IBM Monitoring and Diagnostic Tools for Java - Dump Analyzer > Write Dump Analyzer modules for WAS diagnostics - Tutorial

Tutorial: Writing Dump Analyzer modules for WAS diagnostics

Invoke Another Analyzer

We've already seen examples of how our sample analyzer uses some other analyzers from the standard library, like ObjectWrapperCollection and ObjectWrapper, specifically to help find and access data structures in the dump being analyzed.

That is just one example. In general, a new analyzer may want to call on other pre-existing analyzers to perform a variety of functions that help implement parts of its own new function. Let us extend our sample WASThreadPoolsSample analyzer to call on two other analyzers from the library:

• an analyzer called WASHeader, that produces a standardized informational header suitable for putting at the start of all reports produced by analyzers that deal with WAS processes. This header shows common information like the WAS cell name, server name, the software version, the install root, etc.
• an analyzer called WASVersion, that checks if the version of the WAS process being analyzed, is supported by our new analyzer (since our new analyzer uses knowledge of the names of various WAS data structures and their fields, it may be that these data structures are different in different WAS versions)

public IAnalysisReport produceReport() {

     ...

     /*
         * Print a global header for this report
         */
        WASHeader wasHeader = (WASHeader) getContext().loadAnalyzer(WASHeader.class.getName());
        IAnalysisReport headerReport = wasHeader.produceReport();
        out.printReport("Common WebSphere header information", headerReport, IAnalysisReport.TAG_MAJORHEADING);

     /*
         * Check that the WAS version is compatible with this analyzer (but continue anyway even if not)
         */
        WASVersion wasVersion = (WASVersion) getContext().loadAnalyzer(WASVersion.class.getName());
        wasVersion.checkCompatibleVersion(out, "WASThreadPoolsBasic", new String[] { "7.0" }, false);

     out.startSection("Scanning all thread pools", IAnalysisReport.TAG_MAJORHEADING);

     ....

The key points are as follows:

Load the analyzers

In both cases, we use the construct

getContext().loadAnalyzer(analyzerName)

to obtain a reference to the desired analyzer. getContext() returns a reference to the AnalyzerContext object that is part of the tool infrastructure available to all analyzers, and its loadAnalyzer() method finds the analyzer with a given name (normally its class name) and loads it. Since an analyzer is just a Java class, this method returns a reference to an instance of that Java class, that corresponds to the desired analyzer. We can tell call any methods exported by this analyzer class to perform whichever functions we need from this analyzer.

Note that you will often see other constructs like

WASVersion wasversion = WASVersion.getInstance(getContext(), getContext().getCurrentJavaRuntime())

to load an analyzer. The getInstance() static method is a short-cut, defined in many - but not all - analyzers, to simplify allocation of instances of that analyzer. This method does not do anything more than what the getContext().loadAnalyzer() construct does. But it has the advantage of performing static type checking on the type of analyzer returned, rather than having to do a type-cast that can only be checked at run time. It also can perform static type checking on the (optional) second argument to getInstance() (in this case getContext().getCurrentJavaRuntime(), which is used to pass a parent object to IWrapper-type analyzers. See the API documentation for the various analyzers and the tool framework for further details.

Invoke a report from an analyzer

In the case of the WASHeader analyzer, what we want to do is to obtain the (small) report produced by that analyzer and insert it inside the report generated by our new analyzer. Since WASHeader produces a report, it must implement the IReport interface, so we can just invoke its produceReport() method. This method returns a report object that contains just the report from the WASHeader analyzer. We then insert this report object into the larger report that we are busy generating inside our new analyzer, using the printReport() method.

Note that printReport(), in addition to the report to be inserted, takes two other parameters:

• a title for the report being inserted
• some formatting tags, in this case TAG_MAJORHEADING, which will cause this title to appear as a major heading in the top-level report.

Because we will now have a major heading in the report at the start of the section contributed by the WASHeader analyzer, we also create a new subsection with a major heading "Scanning all thread pools" for the main body of the report. Otherwise, the part of the report listing all the thread pools would appear to be under the heading associated with the WASHeader information.

Invoke specialized methods from an analyzer

As noted above, each analyzer is a Java class, which may export any number of specialized methods in addition to or instead of standardized methods like produceReport(). In this case, the WASVersion analyzer implements a method checkCompatibleVersion(). The purpose of that method is to check if the version of WAS in the dump being analyzed is compatible with a given set of versions specified as a parameter, and to emit a warning message if it is not. In this case, since we wrote our new analyzer primarily to work with WAS 7.0 data structures, we use this method to emit a warning if the WAS version in the dump is anything other than "7.0". This method has several other variations and options; please refer to the API documentation for the WASVersion analyzer for details.

Other analyzers that might be used

As noted earlier, the Dump Analyzer tool ships with a extensive collection of pre-defined "helper" analyzers that can be used to perform various common functions in your analyzers, beside the WASHeader and WASVersion analyzers used in this example.

Some of these "helper" analyzers operate at the WAS level (providing functions related to WAS information in a dump); other "helper" analyzers operate at the JVM level (providing functions related to JVM information in a dump, such as threads, monitors, heaps, etc.). Please refer to the API documentation for the Dump Analyzer tool for a complete list of these analyzers and their functions.

Next Topic

Generate Observations