Package org.openjdk.jmc.flightrecorder.stacktrace

Class StacktraceModel

  • public class StacktraceModel
extends java.lang.Object
    A model for holding multiple stacktraces and their relations to each other.

    The model is stateful in two ways. It uses lazy evaluation to calculate the model, and it contains information about the currently selected path through the tree.

    This class is not thread safe.

    The typical way of using this class is to first decide on the FrameSeparator and then create the model. This is done in constant time. After this you get the root fork and use the StacktraceModel.Fork and StacktraceModel.Branch classes to traverse the tree of stacktraces. Getting the root fork or the end fork of any branch is roughly O(n) to the number of items in the branch.

    Opening a Java flight Recording and setting up the stacktrace model can be done like this: 

     IItemCollection items = JfrLoaderToolkit.loadEvents(file);
 IItemCollection filteredItems = items.apply(JdkFilters.EXECUTION_SAMPLE);
 FrameSeparator frameSeparator = new FrameSeparator(FrameCategorization.METHOD, false);
 StacktraceModel model = new StacktraceModel(true, frameSeparator, filteredItems);
 Fork root = model.getRootFork();

    Traversing the stacktrace tree can be done like this: 

     void walkTree(Fork fork) {
        for (Branch branch : fork.getBranches()) {
                walkTree(branch.getEndFork());
        }
 }

    Examining the contents of a branch can be done by using StacktraceModel.Branch.getFirstFrame() and StacktraceModel.Branch.getTailFrames(). These methods return StacktraceFrame entries that can be queried for more information.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      class  StacktraceModel.Branch
      A branch is a sequence of frames without any forks.
      class  StacktraceModel.Fork
      A fork is a collection of branches that share a common parent branch.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static IMCFrame UNKNOWN_FRAME
      A special marker object that indicates a frame that cannot be determined.

    • Field Detail

      • UNKNOWN_FRAME

        public static final IMCFrame UNKNOWN_FRAME
        A special marker object that indicates a frame that cannot be determined.

        A typical case is when a stacktrace is truncated due to to Flight Recorder settings. We know that there is a frame because of a truncation flag, but there is no information about it.

    • Constructor Detail

      • StacktraceModel

        public StacktraceModel​(boolean threadRootAtTop,
                       FrameSeparator frameSeparator,
                       IItemCollection items)
        Parameters:
        threadRootAtTop - If true, present the thread roots on the first fork. If false, present top frames on the first fork.
        frameSeparator - Determines how different two frames must be to motivate a fork in the model.
        items - Items containing stacktraces. Items in the collection that do not contain stacktraces are silently ignored.

    • Method Detail

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • getRootFork

        public StacktraceModel.Fork getRootFork()
        Return the root fork which contains either top frames or thread roots, depending on the model configuration (threadRootAtTop).

        This is the entry point that you call when you want to access the model structure. After that you use the methods on the StacktraceModel.Fork and StacktraceModel.Branch classes to navigate the model.

        The first call may take some time due to calculations, so it may be useful to call this in a background thread if used in a UI.