Using Java Standard Environment Trace to configure Java trace

Use the Java Standard Environment Trace Settings stanza to configure the IBM® MQ classes for Java trace facility.

com.ibm.msg.client.commonservices.trace.outputName = traceOutputName
traceOutputName is the directory and file name to which trace output is sent.
By default, trace information is written to a trace file in the current working directory of the application. The name of the trace file depends upon the environment that the application is running in:
  • If the application has loaded the IBM MQ classes for Java from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.cl%u.trc.
  • If the application has loaded the IBM MQ classes for Java from the JAR file com.ibm.mq.jar, trace is written to a file called mqjava_%PID%.cl%u.trc.
where %PID% is the process identifier of the application that is being traced, and %u is a unique number to differentiate files between threads running trace under different Java classloaders.

If a process ID is unavailable, a random number is generated and prefixed with the letter f. To include the process ID in a file name you specify, use the string %PID%.

If you specify an alternative directory, it must exist, and you must have write permission for this directory. If you do not have write permission, the trace output is written to System.err.

com.ibm.msg.client.commonservices.trace.include = includeList
includeList is a list of packages and classes that are traced, or the special values ALL or NONE.

Separate package or class names with a semicolon, ;. includeList defaults to ALL, and traces all packages and classes in IBM MQ classes for Java.

Note: You can include a package but then exclude subpackages of that package. For example, if you include package a.b and exclude package a.b.x, the trace includes everything in a.b.y and a.b.z, but not a.b.x or a.b.x.1.
com.ibm.msg.client.commonservices.trace.exclude = excludeList
excludeList is a list of packages and classes that are not traced, or the special values ALL or NONE.

Separate package or class names with a semicolon, ;. excludeList defaults to NONE, and therefore excludes no packages and classes in IBM MQ classes for JMS from being traced.

Note: You can exclude a package but then include subpackages of that package. For example, if you exclude package a.b and include package a.b.x, the trace includes everything in a.b.x and a.b.x.1, but not a.b.y or a.b.z.

Any package or class that is specified, at the same level, as both included and excluded is included.

com.ibm.msg.client.commonservices.trace.maxBytes = maxArrayBytes
maxArrayBytes is the maximum number of bytes that are traced from any byte arrays.

If maxArrayBytes is set to a positive integer, it limits the number of bytes in a byte-array that are written out to the trace file. It truncates the byte array after writing maxArrayBytes out. Setting maxArrayBytes reduces the size of the resulting trace file, and reduces the effect of tracing on the performance of the application.

A value of 0 for this property means that none of the contents of any byte arrays are sent to the trace file.

The default value is -1, which removes any limit on the number of bytes in a byte array that are sent to the trace file.

com.ibm.msg.client.commonservices.trace.limit = maxTraceBytes
maxTraceBytes is the maximum number of bytes that are written to a trace output file.

maxTraceBytes works with traceCycles. If the number of bytes of trace written is near to the limit, the file is closed, and a new trace output file is started.

A value of 0 means that a trace output file has zero length. The default value is -1, which means that the amount of data to be written to a trace output file is unlimited.

com.ibm.msg.client.commonservices.trace.count = traceCycles
traceCycles is the number of trace output files to cycle through.

If the current trace output file reaches the limit specified by maxTraceBytes, the file is closed. Further trace output is written to the next trace output file in sequence. Each trace output file is distinguished by a numeric suffix appended to the file name. The current or most recent trace output file is mqjms.trc.0, the next most recent trace output file is mqjms.trc.1. Older trace files follow the same numbering pattern up to the limit.

The default value of traceCycles is 1. If traceCycles is 1, when the current trace output file reaches its maximum size, the file is closed and deleted. A new trace output file with the same name is started. Therefore, only one trace output file exists at a time.

com.ibm.msg.client.commonservices.trace.parameter = traceParameters
traceParameters controls whether method parameters and return values are included in the trace.

traceParameters defaults to TRUE. If traceParameters is set to FALSE, only method signatures are traced.

com.ibm.msg.client.commonservices.trace.startup = startup
There is an initialization phase of IBM MQ classes for Java during which resources are allocated. The main trace facility is initialized during the resource allocation phase.

If startup is set to TRUE, startup trace is used. Trace information is produced immediately and includes the setup of all components, including the trace facility itself. Startup trace information can be used to diagnose configuration problems. Startup trace information is always written to System.err.

startup defaults to FALSE.

startup is checked before initialization is complete. For this reason, only specify the property on the command line as a Java system property. Do not specify it in the IBM MQ classes for Java configuration file.

com.ibm.msg.client.commonservices.trace.compress = compressedTrace
Set compressedTrace to TRUE to compress trace output.

The default value of compressedTrace is FALSE.

If compressedTrace is set to TRUE, trace output is compressed. The default trace output file name has the extension .trz. If compression is set to FALSE, the default value, the file has the extension .trc to indicate it is uncompressed. However if the file name for the trace output has been specified in traceOutputName that name is used instead; no suffix is applied to the file.

Compressed trace output is smaller than uncompressed. Because there is less I/O, it can be written out faster than uncompressed trace. Compressed tracing has less effect on the performance of IBM MQ classes for Java than uncompressed tracing.

If maxTraceBytes and traceCycles are set, multiple compressed trace files are created in place of multiple flat files.

If IBM MQ classes for Java ends in an uncontrolled manner, a compressed trace file might not be valid. For this reason, trace compression must only be used when IBM MQ classes for Java closes down in a controlled manner. Only use trace compression if the problems being investigated do not cause the JVM itself to stop unexpectedly. Do not use trace compression when diagnosing problems that can result in System.Halt() shutdowns or abnormal, uncontrolled JVM terminations.

com.ibm.msg.client.commonservices.trace.level = traceLevel
traceLevel specifies a filtering level for the trace. The defined trace levels are as follows:
  • TRACE_NONE: 0
  • TRACE_EXCEPTION: 1
  • TRACE_WARNING: 3
  • TRACE_INFO: 6
  • TRACE_ENTRYEXIT: 8
  • TRACE_DATA: 9
  • TRACE_ALL: Integer.MAX_VALUE
Each trace level includes all lower levels. For example, if trace level is set at TRACE_INFO, then any trace point with a defined level of TRACE_EXCEPTION, TRACE_WARNING, or TRACE_INFO is written to the trace. All other trace points are excluded.
com.ibm.msg.client.commonservices.trace.standalone = standaloneTrace

standaloneTrace controls whether the IBM MQ classes for Java client tracing service is used in a WebSphere® Application Server environment.

If standaloneTrace is set to TRUE, the IBM MQ classes for Java client tracing properties are used to determine the trace configuration.

If standaloneTrace is set to FALSE, and the IBM MQ classes for Java client is running in an WebSphere Application Server container, the WebSphere Application Server trace service is used. The trace information that is generated depends upon the trace settings of the application server.

The default value of standaloneTrace is FALSE.