# Using 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.

`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`.

`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. TTUG.tttrc.mkr.2 describes the required and optional arguments for this request.

## 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 + all patterns considered for matching. (default)
`op` toTrace `sender_ptype` toTrace `handler_ptype` toTrace | Optional Optional 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.

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 TTUG.tttrc.mkr.3.

## Error Messages Returned by Session_Trace Request

`Error` | `Description`
`TT_ERR_NO_MATCH` | 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 name 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]

TTUG.tttrc.mkr.4 describes the `tttrace` options.

## 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 `ttrace` 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

TTUG.tttrc.mkr.5 dexplains the messages you may receive during a dispatch trace.

#### Reasons for Dispatch Trace

`Message` | `Explanation`
`tt_message_send` | 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 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

TTUG.tttrc.mkr.6 shows the results.

##### 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

##### 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>

of mylientprogram's message flow is shown in TTUG.tttrc.mkr.7.

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. TTUG.tttrc.mkr.8 describes these commands.

## 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`]...` | State(s) through which to trace messages. 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... `sender_ptypes` toTrace... `handler_ptypes` 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 message from tracing.