Class TraceContext

java.lang.Object
com.ibm.jvm.trace.format.api.TraceContext
public class TraceContext extends Object

  • Field Details

  • Method Details

    • 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(File file) throws IOException
      Throws:
      IOException
      See Also:

    • 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(ByteBuffer data, File messageFile) throws IOException
      Returns:
      Throws:
      IOException
      See Also:

    • getContext

      public static TraceContext getContext(byte[] data, int length, File messageFile) throws IOException
      Throws:
      IOException
      See Also:

    • getContext

      public static TraceContext getContext(byte[] data, int length, File messageFile, PrintStream message, PrintStream error, PrintStream warning, PrintStream debug) throws IOException
      Throws:
      IOException
      See Also:

    • getContext

      public static TraceContext getContext(ByteBuffer data, InputStream messageFile) throws IOException
      Message and warning destinations default to stdout, the error destination defaults to stderr.
      Throws:
      IOException
      See Also:

    • getContext

      public static TraceContext getContext(byte[] data, int length, InputStream messageFile) throws IOException
      Message and warning destinations default to stdout, the error destination defaults to stderr.
      Throws:
      IOException
      See Also:

    • 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()