Module openj9.jvm
Package com.ibm.jvm

Class Trace

  • public final class Trace
extends Object
    The Trace class contains methods for controlling trace and using application trace. This class cannot be instantiated.

    The methods set(String cmd), suspend(), resume(), suspendThis(), resumeThis() and snap() are used to control trace by changing the current trace settings, suspending or resuming tracing globally or just for the current thread and by triggering a snap dump of the current trace buffers.

    The registerApplication(String name, String[] templates) method allows a new trace component and trace points to be registered with trace.

    The trace(int handle, int traceId, ...) methods are used take the application trace points registered by registerApplication(name, formats). The handle value is the integer returned by the registerApplication(name, formats). The traceId is an index into the formats array and the trace(int handle, int traceId, ...) method called must match the types required by the format String formats[traceId].

    If the number or types of the parameters passed to trace(int handle, int traceId, ...) do not match the arguments in formats[traceId] a java/lang/IllegalArgumentException will be thrown.

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static long getMicros()
      Deprecated.
      Use System.nanoTime() instead as this provides as good or better resolution and is more portable.
      static void initializeTrace()
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method does nothing
      static int registerApplication​(String name, String[] templates)
      Registers a new application and trace points for that application with trace.
      static void resume()
      Resumes tracing for all the threads in the JVM.
      static void resumeThis()
      Increments the suspend and resume count for the current thread and resumes tracing the thread if the result is not negative.
      static int set​(String cmd)
      Sets options for the trace subsystem.
      static void snap()
      Trigger a snap dump.
      static void suspend()
      Suspends tracing for all the threads in the JVM.
      static void suspendThis()
      Decrements the suspend and resume count for the current thread and suspends tracing the thread if the result is negative.
      static void trace​(int handle, int traceId)  
      static void trace​(int handle, int traceId, byte b1)  
      static void trace​(int handle, int traceId, byte b1, byte b2)  
      static void trace​(int handle, int traceId, byte b1, byte b2, byte b3)  
      static void trace​(int handle, int traceId, byte b1, String s1)  
      static void trace​(int handle, int traceId, byte b1, String s1, byte b2)  
      static void trace​(int handle, int traceId, char c1)  
      static void trace​(int handle, int traceId, char c1, char c2)  
      static void trace​(int handle, int traceId, char c1, char c2, char c3)  
      static void trace​(int handle, int traceId, char c1, String s1)  
      static void trace​(int handle, int traceId, char c1, String s1, char c2)  
      static void trace​(int handle, int traceId, double d1)  
      static void trace​(int handle, int traceId, double d1, double d2)  
      static void trace​(int handle, int traceId, double d1, double d2, double d3)  
      static void trace​(int handle, int traceId, double d1, String s1)  
      static void trace​(int handle, int traceId, double d1, String s1, double d2)  
      static void trace​(int handle, int traceId, float f1)  
      static void trace​(int handle, int traceId, float f1, float f2)  
      static void trace​(int handle, int traceId, float f1, float f2, float f3)  
      static void trace​(int handle, int traceId, float f1, String s1)  
      static void trace​(int handle, int traceId, float f1, String s1, float f2)  
      static void trace​(int handle, int traceId, int i1)  
      static void trace​(int handle, int traceId, int i1, int i2)  
      static void trace​(int handle, int traceId, int i1, int i2, int i3)  
      static void trace​(int handle, int traceId, int i1, String s1)  
      static void trace​(int handle, int traceId, int i1, String s1, int i2)  
      static void trace​(int handle, int traceId, long l1)  
      static void trace​(int handle, int traceId, long l1, long l2)  
      static void trace​(int handle, int traceId, long l1, long l2, long i3)  
      static void trace​(int handle, int traceId, long l1, String s1)  
      static void trace​(int handle, int traceId, long l1, String s1, long l2)  
      static void trace​(int handle, int traceId, Object o1)  
      static void trace​(int handle, int traceId, Object o1, Object o2)  
      static void trace​(int handle, int traceId, Object o1, String s1)  
      static void trace​(int handle, int traceId, Object o1, String s1, Object o2)  
      static void trace​(int handle, int traceId, String s1)  
      static void trace​(int handle, int traceId, String s1, byte b1)  
      static void trace​(int handle, int traceId, String s1, byte b1, String s2)  
      static void trace​(int handle, int traceId, String s1, char c1)  
      static void trace​(int handle, int traceId, String s1, char c1, String s2)  
      static void trace​(int handle, int traceId, String s1, double d1)  
      static void trace​(int handle, int traceId, String s1, double d1, String s2)  
      static void trace​(int handle, int traceId, String s1, float f1)  
      static void trace​(int handle, int traceId, String s1, float f1, String s2)  
      static void trace​(int handle, int traceId, String s1, int i1)  
      static void trace​(int handle, int traceId, String s1, int i1, String s2)  
      static void trace​(int handle, int traceId, String s1, long l1)  
      static void trace​(int handle, int traceId, String s1, long l1, String s2)  
      static void trace​(int handle, int traceId, String s1, Object o1)  
      static void trace​(int handle, int traceId, String s1, Object o1, String s2)  
      static void trace​(int handle, int traceId, String s1, String s2)  
      static void trace​(int handle, int traceId, String s1, String s2, String s3)  

    • Method Detail

      • initializeTrace

        @Deprecated(forRemoval=true,
            since="1.8")
public static void initializeTrace()
        Deprecated, for removal: This API element is subject to removal in a future version.
        this method does nothing
        This method does nothing.

      • set

        public static int set​(String cmd)
        Sets options for the trace subsystem.

        The trace option is passed in as a String.

        Use the same syntax as the -Xtrace command-line option, with the initial -Xtrace: omitted.

        See Using the -Xtrace option as described in the section on trace options in the documentation for the IBM JVM. Note that some options can only be set at startup on the command line not at runtime using this method.

        This method returns zero on success and non-zero otherwise.

        A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission

        Parameters:
        cmd - the trace options string to set
        Returns:
        0 on success, non-zero otherwise
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings

      • snap

        public static void snap()
        Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • suspend

        public static void suspend()
        Suspends tracing for all the threads in the JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • resume

        public static void resume()
        Resumes tracing for all the threads in the JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • suspendThis

        public static void suspendThis()
        Decrements the suspend and resume count for the current thread and suspends tracing the thread if the result is negative. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • resumeThis

        public static void resumeThis()
        Increments the suspend and resume count for the current thread and resumes tracing the thread if the result is not negative. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • registerApplication

        public static int registerApplication​(String name,
                                      String[] templates)
        Registers a new application and trace points for that application with trace. See Registering for trace as described in the section on Application Trace in the documentation for the IBM JVM.

        The registerApplication() method returns an integer value. Use this value as the handle parameter in subsequent trace() calls. If the registerApplication() method call fails for any reason the value returned is -1.

        When enabling or disabling trace points registered for this application either on the command line or using Trace.set() the trace point id's will be the application name and the index in the template array. For example if you register an application called HelloWorld with three Strings in the template array the trace id's will be HelloWorld.0, HelloWorld.1 and HelloWorld.2 To start printing the third trace point you could call Trace.set() like this: Trace.set("print=HelloWorld.2");

        A security manager check will be made only if the system property com.ibm.jvm.enableLegacyTraceSecurity is set to "true" in which case a check will be made for com.ibm.jvm.TracePermission

        Parameters:
        name - the name of the application you want to trace
        templates - an array of format strings like the strings used by the C printf method
        Returns:
        an int that should be passed to trace() calls as the handle value or -1 on error.
        Throws:
        SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump

      • trace

        public static void trace​(int handle,
                         int traceId)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         String s2,
                         String s3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         Object o1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         Object o1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         int i1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         int i1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         long l1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         long l1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         byte b1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         byte b1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         char c1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         char c1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         float f1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         float f1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         double d1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         double d1,
                         String s1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         Object o1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         Object o1,
                         Object o2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         int i1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         int i1,
                         int i2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         int i1,
                         int i2,
                         int i3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         long l1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         long l1,
                         long l2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         long l1,
                         long l2,
                         long i3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         byte b1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         byte b1,
                         byte b2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         byte b1,
                         byte b2,
                         byte b3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         char c1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         char c1,
                         char c2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         char c1,
                         char c2,
                         char c3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         float f1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         float f1,
                         float f2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         float f1,
                         float f2,
                         float f3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         double d1)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         double d1,
                         double d2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         double d1,
                         double d2,
                         double d3)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         Object o1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         Object o1,
                         String s1,
                         Object o2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         int i1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         int i1,
                         String s1,
                         int i2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         long l1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         long l1,
                         String s1,
                         long l2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         byte b1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         byte b1,
                         String s1,
                         byte b2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         char c1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         char c1,
                         String s1,
                         char c2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         float f1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         float f1,
                         String s1,
                         float f2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         String s1,
                         double d1,
                         String s2)

      • trace

        public static void trace​(int handle,
                         int traceId,
                         double d1,
                         String s1,
                         double d2)

      • getMicros

        @Deprecated
public static long getMicros()
        Deprecated.
        Use System.nanoTime() instead as this provides as good or better resolution and is more portable.
        Returns the microsecond time stamp. The accuracy of the time returned depends on the level of support provided by the particular chip the JVM is running on. In particular the time may not exactly match the time returned by the system clock, so times from this method should only be compared with other times returned from this method.
        Returns:
        the current time in microseconds or 0 if a high-resolution timer is not supported on the platform.