Common Desktop Environment: ToolTalk Messaging Overview

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

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

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

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

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

Generated with CERN WebMaker