+

Search Tips   |   Advanced Search

JRas messages and trace event types


The basic JRas message and event types are not the same as those natively recognized by WAS, so the JRas types are mapped onto the types that are native to the runtime environment. You can control the way JRas message and trace events are processed using custom filters and message controls.

 

Event types

The JRas framework described in this task and its sub-tasks is deprecated. However, we can achieve similar results using Java logging.

The base message and trace event types defined by the stand-alone JRas logging toolkit are not the same as the native types that are recognized by the WAS run-time. Instead, the basic JRas types are mapped onto the native types. This mapping can vary by platform or edition. The mapping is discussed in the following section.

 

Platform message event types

The message event types that are recognized and processed by the WAS runtime are defined in the RASIMessageEvent interface that is provided by the stand-alone JRas logging toolkit.

These message types are mapped onto the native message types, as follows.
WAS native type JRas RASIMessageEvent type
Audit TYPE_INFO, TYPE_INFORMATION
Warning TYPE_WARN, TYPE_WARNING
Error TYPE_ERR, TYPE_ERROR

 

Platform trace event types

The trace event types that are recognized and processed by the WAS run time are defined in the RASITraceEvent interface that is provided by the stand-alone JRas logging toolkit. The RASITraceEvent interface provides a rich and complex set of types. This interface defines both a simple set of levels, as well as a set of enumerated types.

The trace event types are mapped onto the native trace types as follows:

Mapping WAS trace types to the JRas RASITraceEvent level types.
WAS native type JRas RASITraceEvent level type
Event TYPE_LEVEL1
EntryExit TYPE_LEVEL2
Debug TYPE_LEVEL3

Mapping WAS trace types to the JRas RASITraceEvent enumerated types.
WAS native type JRas RASITraceEvent enumerated types
Event TYPE_ERROR_EXC, TYPE_SVC, TYPE_OBJ_CREATE, TYPE_OBJ_DELETE
EntryExit TYPE_ENTRY_EXIT, TYPE_API, TYPE_CALLBACK, TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC
Debug TYPE_MISC_DATA

For simplicity, IBM recommends that one or the other of the tracing type methodologies is used consistently throughout the application. If we decide to use the non-level types, choose one type from each category and use those types consistently throughout the application, to avoid confusion.

 

Message and trace parameters

The various message logging and trace method signatures accept the Object, Object[] and Throwable parameter types. WAS processes and formats the various parameter types as follows:

Primitives

Primitives, such as int and long are not recognized as subclasses of Object type and cannot be directly passed to one of these methods. A primitive value must be transformed to a proper Object type (Integer, Long) before passing as a parameter.

Object

The toString method is called on the object and the resulting String is displayed. Implement the toString method appropriately for any object that is passed to a message logging or trace method. It is the responsibility of the caller to guarantee that the toString method does not display confidential data such as passwords in clear text, and does not cause infinite recursion.

Object[]

The Object[] type is provided for the case when more than one parameter is passed to a message logging or trace method. The toString method is called on each Object in the array. Nested arrays are not handled, that is none of the elements in the Object array belong in an array.

Throwable

The stack trace of the Throwable type is retrieved and displayed.

Array of primitives

An array of primitive, for example, byte[], int[], is recognized as an Object, but is treated somewhat as a second cousin of Object by Java code. In general, avoid arrays of primitives, if possible. If arrays of primitives are passed, the results are indeterminate and can change, depending on the type of array passed, the API used to pass the array, and the release of WAS ND. For consistent results, user code needs to preprocess and format the primitive array into some type of String form before passing it to the method. If such preprocessing is not performed, the following problems can result:

  • [B@924586a0b - This message is deciphered as a byte array at location X. This message is typically returned when an array is passed as a member of an Object[] type and results from calling the toString method on the byte[] type.

  • Illegal trace argument : array of long. This response is typically returned when an array of primitives is passed to a method taking an Object.

  • 01040703: The hex representation of an array of bytes. Typically this problem can occur when a byte array is passed to a method taking a single Object. This behavior is subject to change and cannot be relied on.

  • "1" "2": The String representation of the members of an int[] type formed by converting each element to an integer and calling the toString method on the integers. This behavior is subject to change and cannot be relied on.

  • [Ljava.lang.Object;@9136fa0b : An array of objects. Typically this response is seen when an array containing nested arrays is passed.

 

Controlling message logging

Writing a message to a WAS log requires that the message type passes three levels of filtering or screening:

  1. The message event type must be one of the message event types that is defined in the RASIMessageEvent interface.

  2. Logging of that message event type must be enabled by the state of the message logger mask.

  3. The message event type must pass any filtering criteria that is established by the WAS run-time.

When a logger is obtained from the Manager class, the initial setting of the mask forwards all native message event types to the WAS handler. It is possible to control what messages get logged by programmatically setting the state of the message logger mask.

Some editions of WAS support user specified message filter levels for a server process. When such a filter level is set, only messages at the specified severity levels are written to WAS. Message types that pass the mask check of the message logger can be filtered out by WAS.

 

Control tracing

Each edition of WAS provides a mechanism for enabling or disabling trace. The various editions can support static trace enablement (trace settings are specified before the server is started), dynamic trace enablement (trace settings for a running server process can be dynamically modified), or both. Writing a trace record to a WAS requires that the trace type passes three levels of filtering or screening:

  1. The trace event type must be one of the trace event types that is defined in the RASITraceEvent interface.

  2. Logging of that trace event type must be enabled by the state of the trace logger mask.

  3. The trace event type must pass any filtering criteria that is established by the WAS run-time.

When a logger is obtained from the Manager class, the initial setting of the mask is to suppress all trace types. The exception to this rule is the case where the WAS run time supports static trace enablement and a non-default startup trace state for that trace logger is specified. Unlike message loggers, the WAS can dynamically modify the trace mask state of a trace logger. WAS only modifies the portion of the trace logger mask that corresponds to the values defined in the RASITraceEvent interface. WAS does not modify undefined bits of the mask that might be in use for user-defined types.

When the dynamic trace enablement feature that is available on some platforms is used, the trace state change is reflected both in the application server run time and the trace mask of the trace logger. If user code programmatically changes the bits in the trace mask corresponding to the values defined by in the RASITraceEvent interface, the mask state of the trace logger and the run time state become unsynchronized and unexpected results occur. Therefore, programmatically changing the bits of the mask corresponding to the values defined in the RASITraceEvent interface is not supported.


 

Related tasks


Programming with the JRas framework