Class Trace

java.lang.Object

com.ibm.jvm.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.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ENTRY
static final String	EVENT
static final String	EXCEPTION
static final String	EXCEPTION_EXIT
static final String	EXIT

Method Summary

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)

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

EVENT

public static final String EVENT

See Also:

• Constant Field Values

EXCEPTION

public static final String EXCEPTION

See Also:

• Constant Field Values

ENTRY

public static final String ENTRY

See Also:

• Constant Field Values

EXIT

public static final String EXIT

See Also:

• Constant Field Values

EXCEPTION_EXIT

public static final String EXCEPTION_EXIT

See Also:

• Constant Field Values

Method Details

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.