Module openj9.traceformat
Package com.ibm.jvm.trace.format.api

Class TraceContext

  • public class TraceContext
extends Object

    • Method Detail

      • setRecordThreadNames

        public void setRecordThreadNames​(boolean value)
        Controls whether thread names are captured for inclusion in the information returned by summary(). By default, thread names are not captured unless enabled via this method. Any previously captured names are discarded when subsequently disabled.
        Parameters:
        value - whether thread names should be captured

      • getRecordThreadNames

        public boolean getRecordThreadNames()
        Answer whether thread names are being captured for inclusion in the information returned by summary().
        Returns:
        true if thread names are being captured, false otherwise

      • warning

        public void warning​(Object source,
                    Object message)
        Reports a warning message
        Parameters:
        source - - the object generating the message
        message - - the message to report

      • error

        public void error​(Object source,
                  Object message)
        Reports an error message
        Parameters:
        source - - the object generating the message
        message - - the message to report

      • message

        public void message​(Object source,
                    Object message)
        Reports an informational message
        Parameters:
        source - - the object generating the message
        message - - the message to report

      • debug

        public void debug​(Object source,
                  int level,
                  Object message)
        Reports a debug message
        Parameters:
        source - - the object generating the message
        level - - the debug level of the message
        message - - the message to report

      • setErrorStream

        public void setErrorStream​(PrintStream stream)
        Sets the destination for error messages
        Parameters:
        stream - - destination

      • setWarningStream

        public void setWarningStream​(PrintStream stream)
        Sets the destination for warning messages
        Parameters:
        stream - - destination

      • setDebugStream

        public void setDebugStream​(PrintStream stream)
        Sets the destination for debug messages
        Parameters:
        stream - - destination

      • setMessageStream

        public void setMessageStream​(PrintStream stream)
        Sets the destination for informational messages
        Parameters:
        stream - - destination

      • getVersion

        public float getVersion()
        Returns:

      • getVmVersionString

        public String getVmVersionString()
        A description of the VM that generated the meta-data with which the context was constructed
        Returns:
        - VM description

      • getHighPrecisionResolution

        public BigInteger getHighPrecisionResolution()
        This returns the number of high precision ticks per millisecond as calculated based on trace data processed to date. This value will stabilize over time.
        Returns:
        - ticks per millisecond

      • getRecordSize

        public int getRecordSize()
        The size of the trace records expected by the context
        Returns:
        - size in bytes

      • getHeaderSize

        public int getHeaderSize()
        Returns the size of the meta-data. This allows a file processor to skip to the offset of the first record.
        Returns:
        the length of the meta-data

      • getHeaderSize

        public int getHeaderSize​(ByteBuffer data)
        Constructs a temporary TraceFileHeader from the supplied data and returns it's size offset of the first record.
        Returns:
        the length of the meta-data

      • order

        public ByteOrder order()
        The byte order of the trace data
        Returns:
        - a ByteOrder

      • getTraceType

        public int getTraceType()
        Accessor for the trace type, internal (wraps within a single buffer) or external (no wrapping)
        Returns:
        - trace type

      • setTraceType

        @Deprecated
public void setTraceType​(int type)
        Deprecated.
        this method is deprecated as it's use implies a problem elsewhere
        This forces the trace to a given type. This should only be necessary if you have metadata from a VM when no subscribers were attached and data from a subscriber that was registered afterwards. The inverted case could be true as well, but is much less likely to occur. If you're calling this then you should think about altering the sequence of calls used to get the metadata and trace data.
        Parameters:
        type - - the type of the trace data to process, either TraceContext.INTERNAL or TraceContext.EXTERNAL

      • getTotalTracePoints

        public long getTotalTracePoints()
        The total number of trace points returned to date
        Returns:
        - number of trace points

      • getTotalRecords

        public long getTotalRecords()
        The total number of records processed to date
        Returns:
        - number of records

      • getErrorCount

        public long getErrorCount()
        The number of errors encountered to date
        Returns:
        - number of errors

      • getWarningCount

        public long getWarningCount()
        The number of warnings encountered to date
        Returns:
        - number of warnings

      • addMessageData

        public void addMessageData​(InputStream stream)
                    throws IOException
        Adds additional formatting strings to the set provided when the context was created.
        Parameters:
        stream - - input stream for accessing formatting data
        Throws:
        IOException

      • getPointerSize

        public int getPointerSize()
        Accessor for the pointer size associated with the trace data
        Returns:
        - pointer size in bytes (4 or 8)

      • getContext

        public static TraceContext getContext​(byte[] data,
                                      int length,
                                      InputStream messageFile,
                                      PrintStream message,
                                      PrintStream error,
                                      PrintStream warning,
                                      PrintStream debug)
                               throws IOException
        This method constructs a context that can be used to format trace records produced by the VM instance that created the meta-data provided. The message file is used to format trace points into a human readable form and the print streams provided are where messages of that type are written to
        Parameters:
        data - - trace meta-data
        length - - the length of the meta-data in the array
        messageFile - - a file containing format strings
        message - - informational message destination
        error - - error message destination
        warning - - warning message destination
        debug - - debug message destination
        Returns:
        - a context to use for formatting trace records
        Throws:
        IOException - - if the message data can't be accessed

      • getContext

        public static TraceContext getContext​(ByteBuffer data,
                                      File messageFile,
                                      PrintStream message,
                                      PrintStream error,
                                      PrintStream warning,
                                      PrintStream debug)
                               throws IOException
        This method constructs a context that can be used to format trace records produced by the VM instance that created the meta-data provided. The message file is used to format trace points into a human readable form and the print streams provided are where messages of that type are written to
        Parameters:
        data - - trace meta-data
        messageFile - - a file containing format strings
        message - - informational message destination
        error - - error message destination
        warning - - warning message destination
        debug - - debug message destination
        Returns:
        - a context to use for formatting trace records
        Throws:
        IOException

      • getContext

        public static TraceContext getContext​(ByteBuffer data,
                                      InputStream messageFile,
                                      PrintStream message,
                                      PrintStream error,
                                      PrintStream warning,
                                      PrintStream debug)
                               throws IOException
        This method constructs a context that can be used to format trace records produced by the VM instance that created the meta-data provided. The message file is used to format trace points into a human readable form and the print streams provided are where messages of that type are written to
        Parameters:
        data - - trace meta-data
        messageFile - - an input stream providing access to format strings
        message - - informational message destination
        error - - error message destination
        warning - - warning message destination
        debug - - debug message destination
        Returns:
        - a context to use for formatting trace records
        Throws:
        IOException

      • addData

        public TraceThread addData​(RandomAccessFile file,
                           long offset)
                    throws IOException
        Parameters:
        file - - file containing trace data
        offset - - the offset in the file of the buffer
        Returns:
        - the thread that generated the buffer
        Throws:
        IOException
        See Also:
        addData(TraceRecord)

      • addData

        public TraceThread addData​(byte[] data)
        Parameters:
        data - - a trace buffer generated by the JVM corresponding the context
        Returns:
        - the thread that generated the buffer
        See Also:
        addData(TraceRecord)

      • discardedData

        public void discardedData()
        This method tells the formatter that there was data discarded at this point in the stream of records. This has the affect of discarding any trace point fragments that are awaiting data for completion across all threads. When a trace point iterator encounters one of the locations where data was discarded it will throw a MissingDataException as for records discarded by the trace engine. This makes the assumption that the records are being supplied chronologically.

      • getStartPlatform

        public BigInteger getStartPlatform()
        The time of trace initialization in the traced JVM in high precision format This should be used in conjunction with the system start time
        Returns:
        - high precision start time

      • getStartSystem

        public BigInteger getStartSystem()
        The system time of trace initialization in the traced JVM
        Returns:
        - start time

      • getThreads

        public Iterator getThreads()
        This method provides an iterator to walk the set of known threads; those that have not returned trace points that indicate the thread is exiting. This iterator may be invalidated by adding new trace data to the context.
        Returns:
        - iterator over non-dead threads

      • getTracepoints

        public Iterator getTracepoints()
        This method returns trace points in chronological order on the current data set across threads. This operates on the data available at the time the method is called. If new data is added the oldest trace point from the expanded data set will be returned, irrespective if newer trace points have already been returned.
        Returns:

      • addThreadToFilter

        public void addThreadToFilter​(Long threadID)
        This method adds a thread id to the thread filter. Only those threads in the filter will have data returned via any of the iterators.
        Parameters:
        threadID - - the id of the thread to include in the filter

      • setTimeZoneOffset

        public void setTimeZoneOffset​(int minutes)
        Sets the timezone offset from GMT in +/- minutes to be applied to the time stamp when formatted.
        Parameters:
        minutes - - timezone offset in minutes

      • formatPointer

        public String formatPointer​(long value)

      • summary

        public String summary()

      • setDebugLevel

        public void setDebugLevel​(int level)

      • statistics

        public String statistics()