Syntax for RAS1 traces

Use this syntax 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:

Parameter Description
global_class To view the messages for the data that the TakeSample method collects, add 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 individual variables or flags as the process is running.
  • FLOW (FL): generates a message at an entry or exit point of a function.
  • DETAIL (DE): produces a detailed, verbose level of tracing.
  • INPUT (IN): records data when you run a particular API, function.
  • ALL: records all available messages that are a combination of all the other forms of tracing.
COMP The keyword that indicates this trace will include a component type. use the COMP keyword to trace groups of routines related by function (or component). Do not use this parameter unless you receive a request from IBM® Software Support.
component_type The identifier for a component type. When an IBM Software Support representative instructs you to perform a component trace, the reperesentative provides you a code for that component. Do not use this parameter unless you receive a request from 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, use it only if you receive a request from IBM Software Support.
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 instructs you what value to specify for entry_point.
UNIT The keyword that indicates this trace includes collecting information using the compilation unit, fully qualified, or partially qualified. A system performs a match 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 you are tracing. This value might be one of the components in Table 5, but in practice is most likely the three-character component identifier for the monitoring agent (for example, ks3 for OMEGAMON® for Storage).
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 are required. However, the RAS1 value you set with the global class applies to all components.

A few 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 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 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.