Chapter 4 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 ttrace command has two fundamental modes: server mode and client mode.
-
In server mode, ttrace directs the indicated session to trace by sending it a Session_Trace request.
-
In client mode, ttrace 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 -
ttrace is not downward compatible with older servers or with clients using older versions of libtt. While ttrace 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 tracing 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|
Error |
Description |
|---|---|
|
No handler could be found for the request. |
|
|
ttsession does not have permission to open or create the trace file. |
|
|
The trace file is a directory. |
|
|
There is not enough space in the target file system to create the trace file. |
|
|
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 ttrace 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 ttrace 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 ttrace options.
Table 4-3 tttrace Options
ttrace 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_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 formats:
Tt_message & Tt_pattern { Tt_message & ptype ptid { Tt_message & otype otid {
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
Example 4-1 shows the results.
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 Example 4-2.
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.j HHM 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 ttrace.
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 ttrace script contains settings that control ToolTalk calls and messages. A ttrace 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
- © 2010, Oracle Corporation and/or its affiliates