Syntax for RAS1 traces

This syntax is used to specify an RAS1 trace in the KppENV file. After you add this command to the KppENV file, you must stop and restart the address space for it to take effect. After that, it remains in effect for the life of the address space. To end this RAS1 trace, you must edit the KppENV file again and reset the trace level and stop and start the address space.

The basic syntax of the RAS1 trace commands for error tracing is as follows:


>>-KBB_RAS1=global_class-+-----------------------+-+---------------------+-->
                         '-(COMP:component_type)-' '-(ENTRY:entry_point)-'   

>--+-------------------------+---------------------------------><
   '-(UNIT:unit_name, class)-'

Where:

Parameter	Description
`global_class`	Messages that display the data collected by the TakeSample method can be viewed by adding the RAS1 trace (`UNIT:KRA OUTPUT`) or (`UNIT:KRA ALL`) to the agent trace statement. `ERROR` (ER): returns severe error messages only (this is the default for most applications). `STATE` (ST): records the condition or current setting of flags and variables within the process. If state tracing is enabled, you can see the current state of particular variables or flags as the process is running. `FLOW` (FL): causes a message to be generated at an entry or exit point of a function. `DETAIL` (DE): produces a detailed, verbose level of tracing. `INPUT` (IN): records data that is created in the execution of a particular API, function, or process. `ALL`: causes all available messages to be recorded, a combination of all the other forms of tracing.
COMP	The keyword that indicates this trace will include a component type. The COMP keyword is used to trace groups of routines related by function (or component). Do not use this parameter unless requested to do so by IBM® Software Support.
`component_type`	The identifier for a component type. If an IBM Software Support representative instructs you to perform a component trace, you are provided with a code for that component. Do not use this parameter unless requested to do so by IBM Software Support.
ENTRY	The keyword used to narrow a filtering routine to a specific ENTRY POINT. Since multiple entry points for a single routine are not common, this keyword is not commonly used and should only be used at the explicit request of an IBM Software Support representative.
`entry_point`	A variable representing the name of the entry point. If you are asked to specify a value for the ENTRY keyword, an IBM Software Support representative will tell you what value to specify for `entry_point`.
UNIT	The keyword that indicates this trace will include collecting information using the compilation unit, fully qualified or partially qualified. A match is performed between the compilation unit dispatched and the compilation unit specified on the RAS1 statement. A match results in a trace entry.
`unit_name`	A variable representing the name of the compilation unit. This name can be anything that is related to the object file name or unit compilation name. In most instances, this name defines the component that is being traced. This value might be one of the components in Table 5, but in practice will most likely be the three-character component identifier for the monitoring agent (for example, ks3 for OMEGAMON® for Storage on z/OS®).
`class`	One of the same values specified for Global Class but, because of its position inside the parentheses, the class is narrowed in scope to apply only to the unit_name specified. The following are possible values. Valid abbreviations are in parentheses. `ERROR` (ER): returns severe error messages only (this is the default for most applications. `STATE` (ST): records the condition or current setting of flags and variables within the process. If state tracing is enabled, you can see the current state of particular variables or flags as the process is running. `FLOW` (FL): causes a message to be generated at an entry or exit point of a function. `DETAIL` (DE): produces a detailed, verbose level of tracing. `INPUT` (IN): records data that is created in the execution of a particular API, function, or process. `ALL`: causes all available messages to be recorded, a combination of all the other forms of tracing.

Note:

The default setting for all components is KBB_RAS1=ERROR, meaning that only error tracing is enabled.
You can specify any combination of UNIT, COMP, and ENTRY keywords. None of these keyword is required. However, the RAS1 value you set with the global class applies to all components.

Some examples of RAS1 trace syntax follow.

Example 1: Tracing requests to and answers from the Tivoli Enterprise Monitoring Server:

To show requests to and answers from the Tivoli® Enterprise Monitoring Server, specify this trace:

KBB_RAS1=ERROR (UNIT:KRA ST ERR)

The unit values ST and ERR indicate that you are collecting state and error information for the agent framework component (KRA).

This type of agent trace is used only if you are trying to debug a specific problem, because it greatly increases the number of messages generated by agent. With this type of trace, messages include a detailed dump of all rows of agent data that have passed filtering, which includes attribute names and values, request names, table names, and collection interval. Remember to disable this resource-intensive form of tracing immediately after you have completed your trace.

Example 2: Tracing proxy controller and distributed agent issues:

From the Tivoli Enterprise Monitoring Server, to trace proxy controller and Tivoli Enterprise Monitoring Server distributed agent issues, issue this command:

KBB_RAS1=ERROR (COMP:KUX ST ER) (UNIT:KRA ALL) (UNIT:KDS FL)

In this example:

KUX is a component identifier provided to you by a representative of IBM Software Support so that you can collect state and error information about this subcomponent.
KRA is the unit name for the agent framework component. All trace information about this component is being captured.
KDS is the Tivoli Enterprise Monitoring Server component and the flow (FL) of entry or exit points through this component are documented with records written to RKLVLOG.

Messages that display the data collected by the TakeSample method can be viewed by adding the RAS1 trace (UNIT:KRA OUTPUT) or (UNIT:KRA ALL) to the agent trace statement.