JRas messages and trace event types

This topic describes JRas message and trace event types.

Event types

The base message and trace event types defined by the stand-alone JRas logging toolkit are not the same as the "native" types recognized by the WAS runtime. Instead the basic JRas types are mapped onto the native types. This mapping may vary by platform or edition. The mapping is discussed below.

Platform Message Event Types

The message event types that are recognized and processed by the WAS runtime are defined in the RASIMessageEvent interface 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 recognized and processed by the WAS runtime are defined in the RASITraceEvent interface provided by the stand-alone JRas logging toolkit. The RASITraceEvent interface provides a rich and overly complex set of types. This interface defines both a simple set of levels, as well as a set of enumerated types.

• For a user who prefers a simple set of levels, RASITraceEvent provides TYPE_LEVEL1, TYPE_LEVEL2, and TYPE_LEVEL3. The implementations provide support for this set of levels. The levels are hierarchical (that is, enabling level 2 will also enable level 1, enabling level 3 also enables levels 1 and 2).
• For users who prefer a more complex set of values that can be OR'd together, RASITraceEvent provides TYPE_API, TYPE_CALLBACK, TYPE_ENTRY_EXIT, TYPE_ERROR_EXC, TYPE_MISC_DATA, TYPE_OBJ_CREATE, TYPE_OBJ_DELETE, TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC, and TYPE_SVC.

The trace event types are mapped onto the native trace types. Mapping WAS trace types to JRas RASITraceEvent "Level" types is as follows:

WAS native type	JRas RASITraceEvent level type
Event	TYPE_LEVEL1
EntryExit	TYPE_LEVEL2
Debug	TYPE_LEVEL3

Mapping WAS trace types to JRas RASITraceEvent enumerated types is as follows:

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, it is recommended that one or the other of the tracing type methodologies is used consistently throughout the application. For users who decide to use the non-level types, it is further recommended that you choose one type from each category and use those consistently throughout the application to avoid confusion.

Message and Trace parameters

The various message logging and trace method signatures accept parameter types of Object, Object[] and Throwable. WAS will process and format the various parameter types as follows.

• Primitives

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

• Object

  toString() is called on the object and the resulting String is displayed. The toString() method should be implemented appropriately for any object 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[] is provided for the case when more than one parameter is passed to a message logging or trace method. toString() is called on each Object in the array. Nested arrays are not handled. (i.e. none of the elements in the Object array should be an array).

• Throwable

  The stack trace of the Throwable is retrieved and displayed.

• Array of Primitives

  An array of primitive (e.g. byte[], int[] is recognized as an Object, but is treated somewhat as a second cousin of Object by Java. In general, arrays of primitives should be avoided, if possible. If arrays of primitives are passed, the results are indeterminate and may change depending on the type of array passed, the API used to pass the array and the release of the product. For consistent results, user code should 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 may result.

  • [B@924586a0b - This is deciphered as "a byte array at location X". This is typically returned when an array is passed as a member of an Object[]. It is the result of calling toString() on the byte[]. Illegal trace argument : array of long. This 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 may be seen when a byte array is passed to a method taking a single Object. This behavior is subject to change and should not be relied on. "1" "2" ... : The String representation of the members of an int[] formed by converting each element to an Integer and calling toString on the Integers. This behavior is subject to change and should not be relied on.
  • [Ljava.lang.Object;@9136fa0b : An array of objects. Typically this 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 defined in the RASIMessageEvent interface.
  2. Logging of that message event type must be enabled by the state of the message logger's mask.
  3. The message event type must pass any filtering criteria established by the WAS runtime itself.

  When a WAS logger is obtained from the Manager, the initial setting of the mask is to forward 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's mask.

  Some editions of the product allow the user to specify a message filter level for a server process. When such a filter level is set, only messages at the specified severity levels are written to WAS logs. This means that messages types that pass the message logger's mask check may be filtered out by the WAS itself.

• Controlling Tracing

  Each edition of the product provides a mechanism for enabling or disabling trace. The various editions may 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 defined in the RASITraceEvent interface.
  2. Logging of that trace event type must be enabled by the state of the trace logger's mask.
  3. The trace event type must pass any filtering criteria established by the WAS runtime itself.

  When a logger is obtained from the Manager, the initial setting of the mask is to suppress all trace types. The exception to this rule is the case where the WAS runtime supports static trace enablement and a non-default startup trace state for that trace logger has been specified. Unlike message loggers, the WAS may dynamically modify the state of a trace loggers trace mask. WAS will only modify the portion of the trace logger's mask corresponding to the values defined in the RASITraceEvent interface. WAS will not modify undefined bits of the mask that may be in use for user defined types.

  When the dynamic trace enablement feature available on some platforms is used, the trace state change is reflected both in the Application Server runtime and the trace loggers trace mask. If user code programmatically changes the bits in the trace mask corresponding to the values defined by in the RASITraceEvent interface, the trace logger's mask state and the runtime state will become unsynchronized and unexpected results will occur. Therefore, programmatically changing the bits of the mask corresponding to the values defined in the RASITraceEvent interface is not allowed.