![]() |
![]() |
|
|
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 userlog, 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
xa
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
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
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 userlog, 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"
See Also
![]() |
![]() |
![]() |
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|