Using the Fault Analyzer JVMTI Agent

Fault Analyzer provides a JVMTI (JVM Tool Interface) agent. The agent runs inside a Java™ Virtual Machine (JVM) and can inspect the state of the running Java™ application.

The Fault Analyzer agent is added to the JVM at startup with the following command line option:

java -agentpath:<path-to-agent> <java Class Name>

For example, you could specify this command to run "HelloWorld" using the agent:

java -agentpath:IDIJAGNT.so HelloWorld
Can I add the agent after startup using Java™ instrumentation APIs?
No, the Fault Analyzer agent requests specific JVMTI capabilities that are only available before JVM initialization.
What does the Fault Analyzer Agent do?
When the JVM starts the agent requests that information about local variables be made available by the JVM. This means that the JVM runs in Full Speed Debug (FSD) mode.

For every exception the agent checks if there is a known catch block. If not, the agent creates a fault entry containing the local variables of the current thread stack frames.

What information does the Agent extract?
The agent obtains all accessible local variables with the current thread. The specific information gathered depends upon the kind of stack frames currently that are executing:
  • Java Instance frames:
    • The executing line and file name is extracted
    • All local variable types, name and values are extracted.
    • All fields of the local instance are extracted, including modifiers, types, names, and values.
  • Java static frames:
    • The executing line and file name is extracted
    • All local variable types, names, and values are extracted.
    • The static fields of the declaring class of the method, including static field modifiers, types, names, and values.
  • Native frames:
    • The fields of the "local instance" are extracted, including modifiers, types, names, and values.
  • Static native frames:
    • The static fields of the declaring class of the method, including static field modifiers, types, names, and values.
My Java program called a COBOL program using JNI and that abended. Will the agent report that?
No, the JVMTI API only allows access to Java™ exceptions. When an abend occurs, the JVM is no longer active and the information about local variable names is not available.
What can Fault Analyzer report for a JNI abend?
Fault Analyzer performs a post-mortem analysis using DTFJ APIs.

The DTFJ API allows access to a subset of local variable information; specifically all the object references returned by the JavaStackFrame interface. This API does not provide variable names, only the object values.

For more information about JavaStackFrame and the DTFJ API refer to the documentation for IBM® SDK, Java™ Technology Edition.