The Support Authority: Introducing the Interactive Diagnostic Data Explorer

This new IBM® Diagnostic Tools for Java™ – Interactive Diagnostic Data Explorer, available for IBM Support Assistant 4, is an interactive tool that analyzes data and helps you start troubleshooting, even when you have no idea where to begin. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Adam Pilkington, Master Inventor, Software Engineer, IBM

Photo of Adam PilkingtonAdam Pilkington is the IDDE architect and lead developer. Before joining IBM in 2006 Adam was a J2EE technical architect for a large financial services organisation in the UK. Adam is part of the Java Technology Centre team based in the Hursley Park Development Lab and has worked in both the Java performance and Diagnostic Tooling Framework for Java (DTFJ) teams. He is currently working in the RAS team where he is the lead for IBM's strategic technology for enabling JVM post mortem diagnostics. He is currently focussing on ways to leverage this technology beyond its initial scope, whilst working with both the development and service organisations across IBM labs to ensure it's adoption and ways that it can be enhanced to deliver greater business value. Adam is an IBM developerWorks Contributing Author and an IBM Master Inventor.



24 October 2012

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 -version 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 1. Tools Add-ons menu in ISA 4
Figure 2. JVM-based Tools category
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
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
Figure 4. Getting Started wizard

A quick note on terminology: when using IDDE, the abbreviation "PD" means “problem determination” and refers to the files you are using to determine the cause of the problem being investigated.

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
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
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
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
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
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
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
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
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
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
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.


Conclusion

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.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=842324
ArticleTitle=The Support Authority: Introducing the Interactive Diagnostic Data Explorer
publish-date=10242012