com.ibm.msg.client.services

Class Trace

java.lang.Object

com.ibm.msg.client.services.Trace

public class Trace
extends java.lang.Object

This class allows Tracing to be enabled and disabled dynamically from within an application. Turning trace on or off affects all WebSphere MQ Classes for JMS code in the same JVM.

In addition to using the API in this class, tracing in the WebSphere MQ Classes for JMS can also be monitored and enabled/disabled remotely through the use of the Java Management Extensions (JMX). When the WebSphere MQ Classes for JMS are run on a machine, an MBean is registered with the platform MBeanServer. This will then be available for remote monitoring tools such as JConsole. The MBean will be registered and made available if the JVM is started with Java System properties such as the following:

 -Dcom.sun.management.jmxremote
 -Dcom.sun.management.jmxremote.port=
 -Dcom.sun.management.jmxremote.ssl=false
 -Dcom.sun.management.jmxremote.authenticate=false
 

When a suitable tool, such as JConsole, is used to view the registered MBeans, a domain will be available named IBM WebSphere MQ classes for JMS. Within this domain will be an MBean named TraceControl that will contain methods that match the API provided by this class. These methods can be called remotely through the MBean to query the current tracing behaviour and to enable or disable it while a JMS client application is running.

Finally, if a full client installation (or server installation) is present it is possible to control the IBM WebSphere MQ classes for JMS tracing using the strmqtc/endmqtrc commands. The com.ibm.mq.commonservices.jar must be present on the classpath, and the Java library.path needs to include the WebSphere MQ bin directory. These are not mandatory pre-requisities of the WebSphere MQ classes for JMS so might not be present in all deployments, for example, in an application server. This feature is not available on z/OS of i5/OS.

Method Summary

Methods

Modifier and Type	Method and Description
static int	getTraceLevel() Gets the current trace detail level.
static void	inject(java.lang.String className, java.lang.String description, java.lang.Object data) Allows an application to inject trace points into the trace file This can be useful to provide application relavent information or indications of useful points when providing trace to IBM Service.
static boolean	isOn() Method to return whether trace is enabled or disabled.
static void	setOff() Turns the trace facility off.
static void	setOn() Turns the trace facility on.
static void	setStatus(boolean traceOn) Sets whether trace is enabled or disabled.
static void	setTraceFileAppend(boolean append) Determines if the trace file will be appened to once opened.
static void	setTraceFileCount(int count) Set the number of trace files to cycle through This API must be called BEFORE trace is turned on; once trace has been turned on this API call is in effect ignored even if trace is subsequently turned off again.
static void	setTraceFilename(java.lang.String filename) Sets the trace filename.
static void	setTraceLevel(int newTraceLevel) Sets the tracing detail level.
static void	setTraceLimit(int count) Sets the limit of the size of each trace file This API must be called BEFORE trace is turned on; once trace has been turned on this API call is in effect ignored even if trace is subsequently turned off again.

Methods inherited from class java.lang.Object

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

Method Detail

isOn

public static boolean isOn()

Method to return whether trace is enabled or disabled.

Returns:

true if trace is enabled.

setStatus

public static void setStatus(boolean traceOn)

Sets whether trace is enabled or disabled.

Parameters:

traceOn - whether trace is enabled or not.

setOn

public static void setOn()

Turns the trace facility on.

setOff

public static void setOff()

Turns the trace facility off.

setTraceLevel

public static void setTraceLevel(int newTraceLevel)

Sets the tracing detail level. This value determines the minimum level for which Trace calls will be processed.

Parameters:

newTraceLevel - the minimum level of trace call that is to be processed.

getTraceLevel

public static int getTraceLevel()

Gets the current trace detail level. The higher the value, the more information is traced.

Returns:

the current tracing detail level.

setTraceFileCount

public static void setTraceFileCount(int count)

Set the number of trace files to cycle through This API must be called BEFORE trace is turned on; once trace has been turned on this API call is in effect ignored even if trace is subsequently turned off again. This has the same effect as setting com.ibm.msg.client.commonservices.trace.count in the config file - this call has precedence to the config file.

Parameters:

count - Positive integer - number of files to cycle through 0 - a single file (default)

setTraceFilename

public static void setTraceFilename(java.lang.String filename)

Sets the trace filename. This API must be called BEFORE trace is turned on; once trace has been turned on this API call is in effect ignored even if trace is subsequently turned off again. This has the same effect as setting com.ibm.msg.client.commonservices.trace.outputName in the config file - this call has precedence to the config file.

Parameters:

filename -

setTraceLimit

public static void setTraceLimit(int count)

Sets the limit of the size of each trace file This API must be called BEFORE trace is turned on; once trace has been turned on this API call is in effect ignored even if trace is subsequently turned off again. This has the same effect as setting com.ibm.msg.client.commonservices.trace.limit in the config file - this call has precedence to the config file.

Parameters:

count - Positive integer - data will be written up to that value of bytes per trace file 0 - means no data will be written -1 - means unlimited (default)

setTraceFileAppend

public static void setTraceFileAppend(boolean append)

Determines if the trace file will be appened to once opened. By default a new trace file will be created for each process. Note the default filename includes the process id - therefore even if this is set to true a new file will be created. Set the filename to true. This has the same effect as setting com.ibm.msg.client.commonservices.trace.append in the config file - this call has precedence to the config file.

Parameters:

append - True if files are to appended to.

inject

public static void inject(java.lang.String className,
          java.lang.String description,
          java.lang.Object data)

Allows an application to inject trace points into the trace file This can be useful to provide application relavent information or indications of useful points when providing trace to IBM Service. Values are optional.

Parameters:

className - classname of application class

description - free text description

data - Object that can be incorporated into trace. Will call toString() for the value to be put into trace.