tmtrace(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| File Formats and Data Descriptions Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

tmtrace(5)

Name

tmtrace—Run-time tracing facility

Description

The run-time tracing facility allows application administrators and developers to trace the execution of a BEA Tuxedo application.

Run-time tracing is based on the notion of a trace point, which marks an interesting condition or transition during the execution of an application. Examples of trace points are the entry to an ATMI function such as tpcall, the arrival of a BEA Tuxedo message, or the start of a transaction.

When a trace point is reached, the following things happen. First, a filter is applied to determine if the trace point is of interest. If so, a trace record is emitted to a receiver, which is a file or (in the future) a buffer. Finally, an action is triggered, such as aborting the process. Both the emission to a receiver and the trigger are optional, and neither takes place if the trace point does not pass the filter.

The filter, receiver, and trigger are specified in the trace specification, whose syntax is described below. The trace specification is initialized from the TMTRACE environment variable. The trace specification of a running process may be changed either as a trigger action or by using the changetrace command of tmadmin(1).

Trace points are classified into trace categories, enumerated below. Each trace point belongs to a single category. The filter describes the trace categories of interest, and minimal processing occurs for trace points that do not pass the filter.

Run-time tracing also provides the capability to dye the messages sent by a client to a server, and transitively by that server to other servers. If a process chooses to dye its messages, the dye is automatically passed by the originating process to all processes that directly or indirectly receive messages from the originating process. When a process receives a dyed message, it automatically turns on the atmi trace category and starts emitting trace records to the user log, if this was not being done already.

Dyeing can be explicitly turned on or off by the dye and undye triggers in the trace specification. Dyeing is also implicitly turned on when a dyed message is received, and implicitly turned off by tpreturn() and tpforward(). When it is implicitly turned off, the tracing specification in effect when dyeing was turned on is restored.

Trace Categories

The trace categories are:

atmi

Trace points for explicit application calls to the ATMI and TX interfaces, that is, calls to the tp and tx_ functions, and the invocation of application services There are a few exceptions. Implicit calls are printed in this category where some TX interfaces directly call ATMI interfaces, for the implicit call to tpinit when an ATMI call is done with first calling tpinit(), and for cases where tpreturn is called on error (to aid in debugging).

iatmi

Trace points for Implicit calls to the ATMI and TX interface. These trace points indicate all internal calls made while processing application requests and for administration. Setting this level implies the atmi level, that is, every call to an ATMI or TX interface is traced (both explicit and implicit).

Trace points for every call to the XA interface (the interface between the Transaction Manager and a Resource Manager, for example, a database).

trace

Trace Specification

The trace specification is a string with the syntax filter-spec: receiver-spec [ : trigger-spec] where filter-spec describes the trace categories to be examined or ignored, receiver-spec is the receiver of trace records, and the optional trigger-spec describes the action to be performed.

The NULL string is also a legal trace specification. It is the default for all BEA Tuxedo processes if no other specification is supplied.

The strings on and off are also accepted: on is an alias for atmi:ulog:dye, and off is equivalent to: :undye.

Filter Specification

The filter specification, which is the first component of the trace specification, has the syntax:

[ { + | - } ] [ category ] ...

where category is one of the categories listed above. The symbol * can be used in place of category to denote all categories. The prefix + or - specifies that the following category is to be added or subtracted from the set of categories currently in effect. If no category follows a + or -, then the categories currently in effect are not modified.

An empty filter means that no categories are to be selected, which effectively disables tracing.

When a trace point occurs, its category is compared with the filter specification. If the category is included, then the trace point is processed further—according to the receiver and trigger specifications. If the category is not included, no further processing of the trace point occurs.

Receiver Specification

A receiver is the entity to which a trace record is sent. There is at most one receiver of each trace record.

The receiver specification, which is the second component of the trace specification, has the syntax

[/ regular-expression /] receiver

where the optional regular expression may be used to select a subset of the trace points that pass the filter. The regular expression is matched with the trace record. An empty receiver specification is also legal, in which case no trace records are emitted.

Currently, the only legal value for receiver is:

ulog

Emit the trace record to the user log

Trigger Specification

A trigger is an optional action performed after a trace record is emitted. At most one action is executed for each trace record that passes the filter.

The trigger specification, which is the optional third part of the trace specification, has the syntax:

[/ regular-expression /] action

where the optional regular expression may be used to restrict the trigger so that it is executed only for a subset of the trace points that pass the filter. The regular expression is matched with the trace record.

The available actions are

abort

Terminate the process by calling abort().

ulog(message)

Write the message to the user log.

system(command)

Execute the command using system(3) (this is not supported for Windows clients); occurrences of %A are expanded to the value of trace record.

trace(trace-spec)

Reset the trace specification to the supplied trace-spec.

dye

Turn on message dyeing.

undye

Turn off message dyeing.

sleep(seconds)

Sleep the specified number of seconds (this is not supported for Windows clients).

Trace Records

A trace record is a string with the format:

cc:data

where cc is the first two characters of the trace category and data contains additional information about the trace point.

When a trace record appears in the user log, the line looks like this:

hhmmss.system-name!process-name.pid: TRACE:cc:data

Notices

Match patterns cannot be specified for the receiver and trigger for Workstation clients running on MAC platforms; the regular expressions will be ignored.

The tmadmin changetrace command cannot be used to affect the tracing level for Workstation clients.

Examples

To trace a client, as well as to trace all ATMI calls made by an application server on behalf of that client, set and export TMTRACE=on in the environment of the client. This specification will cause all explicit ATMI trace points in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all explicit ATMI trace points.

To see all client trace points, both explicit and implicit, for the previous example, set and export:

TMTRACE="*:ulog:dye:"

To trace service requests from a client as in the previous example, but restrict the tracing output from the client to the bare minimum of information about tpcall requests, set and export:

TMTRACE=atmi:/tpacall/ulog:dye

in the environment of the client. This specification will cause all tpacall invocations in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all ATMI trace points. The client's identifier, which is included in the tpacall() trace record, can be correlated with the value of the TPSVCINFO parameter passed to any service routine invoked on the client's behalf.

To trace the invocations of all service requests performed by application servers, set:

TMTRACE=atmi:/tpservice/ulog

in the server ENVFILEs on all participating machines.

To enable run-time tracing of all trace categories throughout an application, with message dyeing turned on, set and export:

TMTRACE=*:ulog:dye

in the environment of all clients and in the machine ENVFILEs on all participating machines. This setting will probably produce an unmanageable amount of output because all processes, including the BBL and DBBL, will emit trace records.

To turn on ATMI tracing in all running servers in group GROUP1 after they are booted, invoke the changetrace command of tmadmin as follows:

changetrace -g GROUP1 on

Note that changetrace affects only currently-existing processes; it does not change the trace configuration of servers in group GROUP1 that have not yet been booted. (To set the default trace configuration of a server, set TMTRACE in its ENVFILE.)

To turn off tracing in all currently-running application processes, use changetrace as follows:

changetrace -m all off

To cause the running server process whose identifier is 1 in group GROUP1 to abort when it executes tpreturn, specify the following to tmadmin:

changetrace -i 1 -g GROUP1 "atmi::/tpreturn/abort"