4 Using ToolTalk Tracing

Contents of Chapter:

Accessing ToolTalk Tracing

Controlling Tracing

Controlling libtt Tracing
Controlling Client-Side Tracing

Tracing Message Traffic in a ToolTalk Session

Tracing ToolTalk Calls and Messages through the Server

Formats of Traced Functions
Examples

Settings for ToolTalk Tracing

The ToolTalk ttsession trace shows how ToolTalk pattern matches and delivers every message ttsession sees. ToolTalk tracing for this release also

Displays a single client's interactions with ToolTalk. This feature allows implementors to focus on only one client.
Filters the ttsession trace by, for example, message type, sender, or receiver.

Accessing ToolTalk Tracing

A command new for this release, tttrace, is the primary way to access ToolTalk tracing. This command is similar in purpose and command-line interface to the truss command. It enables you to control the three kinds of ToolTalk tracing. The tttrace command has two fundamental modes: server mode and client mode.

In server mode, tttrace directs the indicated session to trace by sending it a Session_Trace request.
In client mode, tttrace sets an environment variable and executes the ToolTalk client command given on the command line. The environment variable in the executed client instructs libtt whether, and how, to trace client messaging and client API calls.

Note: tttrace is not downward compatible with older servers or with clients using older versions of libtt. While tttrace will detect and diagnose older servers, it fails silently on clients using older versions of libtt.

Controlling Tracing

Controlling libtt Tracing

One way to control libtt's tracing behavior is to set the environment variable $TT_TRACE_SCRIPT .

Note: libtt's tracing fails gracefully if the variable's value is corrupt or inconsistent.

Controlling Client-Side Tracing

The tt_trace_control call sets or clears an internal flag to control all client-side tracing. You can use this call to trace suspect areas in your code. The format of this call is:

int tt_trace_control(int option)

where option 0 to turn traciing off; 1 to turn tracing on; and -1 to toggle tracing on and off. When tracing is on, the extent of tracing is controlled by the TT_TRACE_SCRIPT variable or tracefile. This call returns the previous setting of the trace flag.

Tracing Message Traffic in a ToolTalk Session

The Session_Trace request is a ToolTalk request that ttsession registers to handle itself; that is, ttsession is the handler for the Session_Trace request. This request can be sent by any ToolTalk client, and, although not recommended, other ToolTalk clients can register to handle this request. (Note: This method will cause tracing to not work.) The syntax for this request is:

[file] Session_Trace(    in     boolean           on,
                         in     boolean           follow
                         [in    attribute         toPrint
                         |in    state             toTrace
                         |in    op                toTrace
                         |in    handler_ptype     toTrace
                         |in    sender_ptype      toTrace][...] );

The Session_Trace request turns message tracing in the scoped-to session on or off.

If tracing is on and the file attribute of the request is set, subsequent trace output is appended to the file named by the attribute.
If tracing is on and the file attribute is not set, tracing continues to the current trace.

By default, daemon mode causes the output to go to the console of the host on which ttsession is running; job-control mode causes the output to go to ttsession's standard error. Table 4-1 describes the required and optional arguments for this request.

Table 4-1: Session_Trace Agurments

Argument Description

boolean on Required Turn tracing on or off. If no toTrace arguments are included and on is true, the previous trace settings are restored.

boolean follow Required Turn on client-side tracing for Invoked clients.

attribute toPrint Optional Print attribute(s) for each message traced. Valid attributes are:

none - print only a one-line description of traced messages (default)

all - print all attributes of traced messages.

state toTrace Optional State(s) through which to trace messages. In addition to the Tt_states defined in tt_c.h, valid states are:

edge - messages entering initial (TT_SENT) and final (TT_HANDLED), (TT_FAILED) states.

deliver - all state changes and all client deliveries.

dispatch - deliver plus all patterns considered for matching. (default)

op toTrace Optional Trace messages that have toTrace as a value for the indicated message attribute.

Any number of toTrace arguments may be included in the request.

toTrace may include sh wildcard characters.

If no toTrace argument is included for a given message attribute, no value of that attribute excludes a message from tracing.

sender_ptype toTrace Optional

handler_ptype toTrace Optional

The current session tracing behavior changes only if this request is not failed. On failure, the tt_message_status of the reply is set to one of the errors described in Table 4-2.

Table 4-2: Error Messages Returned by Session_Trace Request

Error Description

TT_ERR_NOMATCH No handler could be found for the request.

TT_ERR_APPFIRST + EACCES ttsession does not have permission to open or create the trace file.

TT_ERR_APPFIRST + EISDIR The trace file is a directory.

TT_ERR_APPFIRST + ENOSPC There is not enough space in the target file system to create the trace file.

TT_ERR_APPFIRST + EEXIST Tracing is already occurring on another file. ttsession resets the file attribute of the reply to match the existing trace file. To trace to a different file, first turn off tracing to the current trace file.

Tracing ToolTalk Calls and Messages through the Server

The tttrace function traces message traffic through the server for the indicated ToolTalk session, or runs a command with ToolTalk client tracing turned on. If neither the session nor the command is given, the default session is traced. By default, tracing terminates when tttrace exits. The syntax for this function is:

tttrace [-0FCa] [-o outfile ] [-S session | command] 
tttrace [-e script | -f scriptfile ] [-S session | command]

Table 4-3 describes the tttrace options.

Table 4-3: tttrace Options

Option Description

-0 Turns off message tracing in session, or runs the specified command without message tracing (that is, with only call tracing).

-F Follows all children forked by the indicated command, or subsequently started in session by ttsession. Normally, only the indicated command or a ttsession instance is traced. When the -F option is specified, the process ID is included with each line of trace output to indicate which process generated it.

-C Do not trace client calls into the ToolTalk API. The default is to trace the calls.

-a Prints all attributes, arguments and context slots of traced messages. The default is to use only a single line when printing a message on the trace output.

-o outfile The file to be used for the trace output. For session tracing, output goes to standard output of tttrace.

-S session The session to trace. Defaults to the default session, that is, the session that tt_open would contact.

command The ToolTalk client command to invoke and trace.

-e script The script to be used as a tttrace setting.

-f scriptfile The file from which to read the tttrace settings.

tttrace is implemented purely as a ToolTalk client, using the message interface to ttsession and the TT_TRACE_SCRIPT environment variable. If this variable is set, it tells libtt to turn on client-side tracing as specified in the trace script. If the first character of the value is '.' or '/', the value is taken to be the path name of file containing the trace script to use; otherwise, the value is taken to be an inline trace script.

Formats of Traced Functions

The following is an example of how a traced ToolTalk function looks.

[pid] function_name(params) = return_value (Tt_status)

Message Summary Format

The -a option prints message attributes after a one-line summary of the message, as follows:

Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope): status == Tt_status

State Change Format

State changes are indicated by the following format:

old_state => new_state.

Message Delivery Format

Deliveries are indicated by the following indicated:

Tt_message => procid recipient_procid

Table 4-4 dexplains the messages you may receive during a dispatch trace.

Table 4-4: Reasons for Dispatch Trace

Message Explanation

tt_message_sent The message to send.

tt_message_reject The message was rejected

tt_message_fail The message failed.

tt_message_reply The reply to a message.

tt_session_join The session to join.

tt_file_join The file to join.

tt_message_reply A client called the indicated function.

tt_message_send_on_exit ttsession is dispatching on_exit messages for a client that disconnected before calling tt_close.

tt_message_accept ttsession is dispatching messages that had been blocked while a ptype was being started. The started client has now called either tt_message_accept or tt_message_reply to indicate that the ptype should be unblocked.

TT_ERR_PTYPE_START A ptype instance was started to receive the message, but the start command exited before it connected to ttsession.

TT_ERR_PROCID ttsession has lost its connection to the client that was working on this request.

ttsession -> ttsession Another session wants this session to find recipients for the message.

ttsession <- ttsession Another session wants to update (for example, fail) a message originating in this session.

Matching Format

When dispatching is being traced, matching is indicated by one of the following

Tt_message & Tt_pattern { 
Tt_message & ptype ptid { 
Tt_message & otype otid {

formats:

The pattern or signature is printed, followed by:

} == match_score; [/* mismatch_reason */]

Examples

This sections contains examples of how to use the tttrace function.

Registering a Pattern and Sending a Matching Notice

To register a pattern and send a notice that matches the pattern, type:

% tttrace -a myclientprogram

Code Example 4-1 shows the results.

Code Example 4-1: Registering a Pattern and Sending a Notice

tt_open() = 0x51708=="7.jOHHM X 129.144.153.55 0" (TT_OK)
tt_fd() = 11 (TT_OK)
tt_pattern_create() = 0x50318 (TT_OK)
tt_pattern_category_set(0x50318, TT_OBSERVE) = 0 (TT_OK)
tt_pattern_scope_add(0x50318, TT_SESSION) = 0 (TT_OK)
tt_pattern_op_add(0x50318, 0x2f308=="Hello World") = 0 (TT_OK)
tt_default_session() = 0x519e0=="X 129.144.153.55 0" (TT_OK)
tt_pattern_session_add(0x50318, 0x519e0=="X 129.144.153.55 0") = 0 (TT_OK)
tt_pattern_register(0x50318) = 0 (TT_OK)
tt_message_create() = 0x51af0 (TT_OK)
tt_message_class_set(0x51af0, TT_NOTICE) = 0 (TT_OK)
tt_message_address_set(0x51af0, TT_PROCEDURE) = 0 (TT_OK)
tt_message_scope_set(0x51af0, TT_SESSION) = 0 (TT_OK)
tt_message_op_set(0x51af0, 0x2f308=="Hello World") = 0 (TT_OK)
tt_message_send(0x51af0)    ...
    TT_CREATED => TT_SENT: 
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:             0 7.jOHHM X 129.144.153.55 0
    op:             Hello World
    session:        X 129.144.153.55 0
    sender:         7.jOHHM X 129.144.153.55 0
= 0 (TT_OK)
tt_message_receive()    ...
    Tt_message => procid <7.jOHHM X 129.144.153.55 0>
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:             0 7.jOHHM X 129.144.153.55 0
    op:             Hello World
    session:        X 129.144.153.55 0
    sender:         7.jOHHM X 129.144.153.55 0
    pattern:        0:7.jOHHM X 129.144.153.55 0
= 0x51af0 (TT_OK)

To see ttsession's view of the message flow, type:

% tttrace -a

ttsession's view of mylientprogram's message flow is shown in Code Example 4-2.

Code Example 4-2: ttsession's View of Trace

tt_message_reply: 
    TT_SENT => TT_HANDLED: 
    TT_HANDLED TT_PROCEDURE TT_REQUEST (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:        0 2.jOHHM X 129.144.153.55 0
    op:        Session_Trace
    args:      TT_IN string: "> /tmp/traceAAAa002oL; version 1; states"[...]
    session:   X 129.144.153.55 0
    sender:    2.jOHHM X 129.144.153.55 0
    pattern:   0:X 129.144.153.55 0
    handler:   0.jOHHM X 129.144.153.55 0
    Tt_message => procid <2.jOHHM X 129.144.153.55 0>
tt_message_send: 
    TT_CREATED TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:        0 7.jOHHM X 129.144.153.55 0
    op:        Hello World
    session:   X 129.144.153.55 0
    sender:    7.jOHHM X 129.144.153.55 0
    TT_CREATED => TT_SENT: 
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:        0 7.jOHHM X 129.144.153.55 0
    op:        Hello World
    session:   X 129.144.153.55 0
    sender:    7.jOHHM X 129.144.153.55 0
    Tt_message & Tt_pattern {
    id:        0:7.jOHHM X 129.144.153.55 0
    category:  TT_OBSERVE
    scopes:    TT_SESSION 
    sessions:  X 129.144.153.55 0
    ops:       Hello World 
    } == 3;
    Tt_message => procid <7.jOHHM X 129.144.153.55 0>

Note: The first message traced will almost always be ttsession's reply to the request sent to it by tttrace.

Tracing a Message Flow

To trace the message flow in a specific, non-default session, type:

% tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"

where "01 15303 1342177284 1 0 13691 129.144.153.55 2" is the specific, non-default session to be traced.

Settings for ToolTalk Tracing

A tttrace script contains settings that control ToolTalk calls and messages. A tttrace script consists of commands separated by semicolons or newlines. If conflicting values are given for a setting, the last value is the one used. Table 4-5 describes these commands.

Table 4-5: tttrace Script Commands

Command Description

version n The version of the tttracefile command syntax used. The current version is 1.

follow [off|on] Sets whether to follow all children forked by the traced client or subsequently started in the traced session. Default is off.

[>|>>] outfile File to be used for the trace output. By default, trace output goes to standard error. Normal shell interpretation of > and >> applies.

functions [all|none|func...] ToolTalk API functions to trace. func may include shell wildcard characters. Default is all.

attributes [all|none] none (default) means use only a single line when printing a message on the trace output; all means print all attributes, arguments, and context slots of traced messages.

states [none|edge|deliver|
dispatch|Tt_state...] States through which to trace mesages. In addition to the Tt_states defined in tt_c.h, valid states are:

none - disable all message tracing.

edge - messages entering initial (TT_SENT) and final (TT_HANDLED), (TT_FAILED) states.

deliver - all state changes and all client deliveries.

dispatch - deliver plus all patterns considered for matching (default).

ops toTrace Trace messages that have toTrace as a value for the indicated message attribute. toTrace may include shell wildcard characters. If no toTrace argument is included for a given message attribute, then no value of that attribute excludes a mesasge from tracing.

sender_ptypes toTrace

handler_ptypes toTrace