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.
When you don't know where to begin
IBM Diagnostic Tools for Java – Interactive Diagnostic Data Explorer (IDDE), is a newly released tool for analysing diagnostic artifacts, such as core files or IBM PHD files. IDDE is an interactive problem solving tool for situations in which you are not actually sure what the problem is, and you want to explore the information you have available to see what data can be used to resolve the issue. This is in contrast to, say, an out-of-memory error, for which you would want to run a tool such as Memory Analyzer to produce a report of possible memory-related problems. As a result of your investigation, you might still end up realizing that you have a memory problem and need to run Memory Analyzer, but this might not have been the obvious direction to take to start with.
This article will take you through creating a core file and installing IDDE into IBM Support Assistant (ISA) 4, and provide a quick overview of the component parts of the tool and what they do. Finally, an example will apply IDDE to a core file to learn some basic information about IBM WebSphere Application Server.
Getting started with the tool
IDDE can analyse core files (as well as IBM javacores and PHD files) that
can either be produced on demand or as a result of a VM error condition.
Depending upon the version of WebSphere Application Server (and hence the
underlying version of Java™) that produced these files, a post
processing step of running
jextract might be required. You should consult the relevant diagnostics or user guide to determine the exact procedure to perform. Initially, to keep things simple, this example will just use a standard IBM Java SDK to generate a small core file that can be loaded into IDDE.
One of the easiest ways to create a core is to enter this command on a command line:
java -Xdump:system:events=vmstop,file=core.dmp -version
What this does is instruct the JVM to create a core file on exit.
Normally, though, you would also be required to run a program as well. A
trick you can use is to supply the
parameter; enough of the JVM will be started to provide you with
classloaders, heaps, and other components that can be examined without
needing an application. The core file that is produced will be in a file called core.dmp in the current directory.
Be aware that the above is the Windows® version of the command; other operating systems might require some minor syntax alterations to achieve the same result. Consult the diagnostics guide for your platform for exact details of the supported parameters.
Install IDDE into ISA 4
IDDE is currently available for ISA 4 and the diagrams that follow show how to locate and install it from the list of available tools.
IDDE is located under the Tools Add-ons menu in ISA 4 (Figure 1) and is found in the JVM-based Tools category (Figure 2).
Figure 1. Tools Add-ons menu in ISA 4
Figure 2. JVM-based Tools category
Tick the IDDE box and follow the installation instructions.
Your first investigation
One IDDE is installed, you can launch it from the Launch Activity > Analyze Problem option, where it will be included in the list of tools (Figure 3).
Figure 3. Launch IDDE
When IDDE is first run, it will detect that you don't have any projects within which you can save your analysis, and so it will automatically run the Getting Started wizard, which will create one for you. You can give the project any name you want, so, for example, you can organise your investigations by application, or use whatever naming scheme makes sense for you (Figure 4).
Figure 4. Getting Started wizard
As this is the first time IDDE is being launched, it will then also run the New PD Artifact wizard, which will enable you to point IDDE at the core file you created earlier.
Use the Browse button to find the core file created earlier (Figure 5) and then choose whether or not to copy the file into the ISA project. This is a housekeeping option that enables you to keep all your investigation files together in IDDE or link to them elsewhere. Selecting the Copy artifact into workspace option will result in two versions of the file; therefore, if it is a very large file then selecting Link to artifact might be more appropriate. Click Finish when you are done and IDDE will be ready to look at the file.
Figure 5. Locate core file
Navigating and investigating
The PD Navigator shows you projects and files within each project that are available for analysis. When a new artifact is added (in this case a core file), then it is shown in the tree as being ready for investigation.
At this stage, IDDE can determine that it is a file it recognises but doesn't yet know anything more about its contents. To find out more, expand or double click on Start Investigation (Figure 6).
Figure 6. Start Investigation
IDDE now knows some more things about the file: it identifies it as a core file, the platform it came from, and the version of Java that it contained. This simple operation has highlighted two important IDDE characteristics:
- IDDE utilises an incremental approach for its analysis. Data that can be quickly retrieved is done automatically; more costly operations are deferred until explicitly requested by the user. IDDE doesn't try and guess what you want to do, but will always be building up a picture of what you are looking at from all the data it receives.
- When IDDE receives new data, it can potentially change its user interface to reflect its improved understanding of the context within which you are working. So, in the example above, the navigator tree will now always contain more data about the type of core file.
You now have some basic information about the core file, but digging deeper will require you to open the investigation log, which is a file that is automatically created when you start an investigation, and is intended to provide a record of your thoughts plus data from the core file during the course of the investigation. You open the log by double clicking on Investigation Log in the PD Navigator (Figure 7).
Figure 7. Open Investigation Log
The log is actually a text editor that uses an innovative mechanism for blending static text and live data from the file under analysis. Being an Eclipse text editor, it supports all the usual operations and functions you would expect, such as find/replace, syntax highlighting, and auto-complete. The lines of text in grey at the top, which start with “#,” are IDDE meta-data which you can ignore. To start this investigation, you want to know a little bit more about the system from which the core file came, so type that thought into the editor to record your investigative train of thought (Figure 8).
Figure 8. Add comments to editor
Now, you want to get that information from the core file. Entering “!”
into the editor will display a list of commands that you can run.
Scrolling up and down the list will display help for the command currently
selected. Looking down the list, the
info sys command looks like it will give you what you need (Figure 9).
Figure 9. List of commands
Pressing Enter with this command selected will insert the text into the editor. Notice how IDDE has recognised this text as actually being a command and used syntax highlighting to bring it to your attention. Now press Ctrl+Enter, which is a special key combination that instructs IDDE to take all of the text from the left of the current cursor position and execute it as a command against the core file. The results will then be inserted into the editor (Figure 10)
Figure 10. Add data to editor
As you scroll through the list of commands, you will notice that some have different icons. Some commands are plugins that are shipped with IDDE and provide more information than is available in the standard commands. They have also been written so that the output is in the form of further IDDE commands, which can be executed by placing the cursor in the resulting text and pressing Ctrl+Enter. Figure 11 shows an example from !javaclassloaders; notice how the output is recognised as other commands by IDDE.
Figure 11. IDDE output
The simple mechanics of pressing Ctrl+Enter to execute commands is the key concept for being able to drive the IDDE editor and find the information that you need. Using the output from commands to execute subsequent ones provides a very quick method for drilling down into the available data. Remember, though, that it is all still text, so feel free to add your own annotations — or even edit the returned data to highlight something of particular interest.
Now that you have the basics, let's walk through finding some actual data using a core file generated from a running WebSphere Application Server system.
Finding your WebSphere Application Server system details using IDDE
In this section, you will see how you can use IDDE to find out what version of WebSphere Application Server you are running. (WebSphere Application Server is only being referenced as an example. The general principles covered here of finding particular objects in the heap and examining their values are equally applicable to any other application.)
The first command to use is
x/j, which will find all the objects of a particular class (remember that content-assist will show you all the available commands together with their help). The result of this is shown in Figure 12. Some of the total output has been removed for clarity, but this nicely illustrates how you can use IDDE to modify the output from commands to make it easier for others to read and interpret.
Figure 12. x/j command output
The output shows that the command found one of these objects. It also
shows the class structure. Looking at the class hierarchy, the field you
are now interested in is the product instances array, so the next step is
to have a look at that object. You can use the
javaobject command to examine this instance in depth (Figure 13).
Figure 13. javaobject command output
This is one of the new IDDE aware commands, and you can see that the
output contains further commands that can be executed. From the output, you can see that the WebSphere Application Server product array contains a single entry which you can examine with a second
javaobject command (Figure 14).
Figure 14. Second javaobject command output
You can now see the version of WebSphere Application Server that you are running.
In terms of solving your own application problems, starting with a known class and then following the class hierarchy to retrieve values that are of interest to you is a common diagnostic pattern that you can apply using IDDE.
This article introduced IBM's new Interactive Diagnostic Data Explorer tool, which is targeted to situations where you need flexibility navigating around your data, rather than using a batch or report-driven tool. Simple instructions outlined how you can start your investigation and then use a hybrid editor to record your steps and interact with the artifact under analysis. A real world example showed how you can find some application specific information using WebSphere Application Server as the application.
IDDE is currently available as a Tech Preview. We would be very interested to hear any feedback or suggestions you have for further development ideas. You can send us your feedback via the IDDE developerWorks group.
- IBM Support Assistant 5.0 Beta home page
- Fix Central
- IBM Support Portal
- The Support Authority: If you need help with WebSphere products, there are many ways to get it
- IBM Software product Information Centers
- IBM Software Support Web site
- IBM Education Assistant
- IBM developerWorks
- IBM Redbooks
- WebSphere Software Accelerated Value Program
Get products and technologies
- IBM Support Assistant (ISA): Download as either the embedded server or the EAR file deployment.
- IBM Software Support Toolbar
- IBM Support Assistant Forum
- IBM Application Pattern for Java blog
- WebSphere and CICS Support Blog
- Forums and newsgroups
- Java technology Forums
- WebSphere Support Technical Exchange on Facebook
- Global WebSphere Community on WebSphere.org
- Follow IBM Support on Twitter!