# ToolTalkトレースの使い方

ToolTalk
ttsessionトレースは、ToolTalkパターンをttsessionにある各メッセージと 一致させ配信する方法を示します。本リリースのToolTalkトレースは次のことを行い ます。

- 単一クライアントのToolTalkとの対話を表示します。この機能により、実行者は１つ のクライアントだけをトレースできます。

- ttsessionトレースを、たとえばメッセージ型、送信者、または受信者ごとといった フィルタに通します。

## ToolTalkトレースへのアクセス

本リリースの新規コマンドである
`tttrace`は、おもにToolTalkトレースへのアクセスに 使用します。このコマンドは、用途やコマンド行インタフェースの点で、
`truss`コマンドに似ています。このコマンドにより、３ 種類のToolTalkトレースをコントロールできます。
`tttrace`コマンドには、
サーバ ・モードと
クライアント・モードの２つの基本 モードがあります。

- サーバ・モードでは、Session_Trace要求を送信することによって、 `tttrace`が指定されたセッションのトレースを指示します。

- クライアント・モードでは、`tttrace`は環境変数を設定し、コマ ンド行に指定されたToolTalkクライアント・コマンドを実行します。実行されたクライアン トの環境変数は、クライアント・メッセージとクライアントAPI呼び出しをトレースするか どうかとその方法を
  `libtt`に指示します。

`tttrace`は、旧バージョンのサーバや、 `libtt`の旧バージョンを使用するクライアントとの下位互換性はありま せん。`tttrace`は旧バージョンのサーバを検出して診断する一方で、 `libtt`の旧バージョンを使用するクライアント上で何も通知せずに 異常終了します。.

## トレースのコントロール

### libttトレースのコントロール

`libtt`トレースの動作をコントロールする方法の１つは、
環境変数 `$
TT_TRACE_SCRIPT`を設定することです。

`libtt`のトレースは、変数の値が正確でなかったり、一貫性が ない場合は異常終了します。

### クライアント側トレースのコントロール

The
`tt_trace_control`呼び出しは、内部フラグを設定また はクリアして、すべてのクライアント側トレースをコントロールします。この呼び出しを 使用して、コード内の問題の領域をトレースします。この呼び出しの形式は次のとおりで す。

    int tt_trace_control(int option)

optionの値として0を指定するとトレースをオフ にし、1を指定するとトレースをオンにします。-1を指定すると、トレースのオンとオフを 切り替えます。トレースがオンの場合は、トレースの範囲を
`TT_TRACE_SCRIPT`変数かトレースファイルでコントロー ルします。この呼び出しは、トレース・フラグの以前の設定を返します。

## ToolTalkセッション内のメッセージ・トラフィックのトレース

Session_Trace要求は、ttsessionがそれ自身を処理するために登録する ToolTalk要求です。つまり、ttsessionはSession_Trace要求のハンドラです。この要求は、 どのToolTalkクライアントでも送信できます。お勧めできる方法ではありませんが、この 要求を処理するために他のToolTalkクライアントを登録できます。（注：この方法では トレースは行われません。）この要求の構文は次の とおりです。

    [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][...] );

Session_Trace要求は、配信範囲指定されたセッションでのメッセージ・トレースを オンまたはオフにします。

- トレースがオンで、要求のファイル属性が設定されている場合、後続のトレース出力 は属性が名前を付けたファイルに付け加えられます。

- トレースがオンで、ファイル属性が設定されていない 場合、トレースは現在のトレースを続行します。

デフォルトの場合、デーモン・モードではttsessionを実行中 のホストのコンソールが出力先になります。ジョブ・コントロール・モードでは、 ttsessionの標準エラーが出力先になります。 TTUG.tttrc.mkr.2は、この要求の必須 およびオプションの引き数を示しています。

## Session_Trace引き数

`引き数` |  | `説明`
`boolean` on | 必須 | トレースをオンまたはオフにします。toTrace引き数 がなくonがtrueの場合は、前のトレース設定が復元されます。
`boolean` follow | 必須 | 起動したクライアントのクライアント側トレースをオンにします。
`attribute` toPrint | オプション | トレースされた各メッセージの属性を出力します。 有効な属性は次のとおりです。 • none–トレースされた各メッセージの記述を１行だけ 出力（デフォルト） • all–トレースされたメッセージの属性全部を出力
`state` toTrace | オプション | メッセージをトレースするための状態。 `tt_c.h`に定義されているTt_statesの他に有効な 状態は次のとおりです。 • edge–初期の状態(`TT_SENT`) と最後の状態(`TT_HANDLED`, `TT_FAILED`) を入力しているメッセージ • deliver–すべての状態の変更と、すべてのクライアントの 配信 • dispatch–deliver状態および一致 するように考慮されたすべてのパターン（デフォルト）
`op` toTrace `sender_ptype` toTrace `handler_ptype` toTrace | オプション オプション オプション | 表示されたメッセージの属性の値としてtoTraceを 持っているトレース・メッセージ •要求には、toTrace引き数を任意の数だけ 含めることができます。 • toTraceには`sh`(シェル）のワイルドカード文字も指定できます。 • 指定のメッセージ属性に対してtoTrace引き数がない場合、トレースから メッセージを除外する属性の値もありません。

現在のセッション・トレースの動作には、この要求が失敗しない場合にのみ変更され ます。失敗した場合には、応答の`tt_message_status` は、 TTUG.tttrc.mkr.3で説明されている エラーの１つに設定されます。

## Session_Trace要求が返すエラー・メッセージ

`エラー` | `説明`
`TT_ERR_NO_MATCH` | 要求に対するハンドラを見つけることができません。
`TT_ERR_APPFIRST + EACCES` | ttsessionがトレース・ファイルを開くまたは作成するためのアクセス権を 持っていません。
`TT_ERR_APPFIRST + EISDIR` | トレース・ファイルがディレクトリです。
`TT_ERR_APPFIRST + ENOSPC` | ターゲット・ファイル・システムにトレース・ファイル作成の 十分なスペースがありません。
`TT_ERR_APPFIRST + EEXIST` | トレースがすでに別のファイルで行われています。 ttsessionは、応答のファイル属性を再設定して既存のトレース・ファイルの名前を付け ます。別のファイルへのトレースを行うには、最初に現在のトレース・ファイルへの トレースをオフにします。

## サーバによるToolTalk呼び出しとメッセージのトレース

`tttrace`関数は、指定のToolTalkセッションのために サーバによりメッセージ・トラフィックをトレースするか、ToolTalkクライアント・トレー スをオンにしてコマンドを実行します。セッションとコマンドの両方とも指定されない場合 は、デフォルトのセッションがトレースされます。デフォルトでは、`tttrace` が終了するとトレースも終了します。この関数の構文は次のとおりです。

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

TTUG.tttrc.mkr.4では、 `tttrace`オプションにつて説明します。

## tttraceオプション

`Option` | `Description`
`-0` | セッション内のメッセージ・トレースをオフにするか、メッセージ・トレー スを行わないで（つまり呼び出しのトレースだけを行って）指定コマンドを実行します。
`-F` | 指定のコマンドによってフォークされた、またはttsessionによりセッション 内で続けて起動されたすべての子を追跡します。通常、指定のコマンドだけかttsession インスタンスがトレースされます。`-F`オプションが指定されている 場合、プロセスIDがトレース出力の各行に表示され、どのプロセスが生成したかを示しま す。
`-C` | ToolTalk APIへのクライアント呼び出しをトレースしないようにします。 デフォルトでは呼び出しをトレースします。
`-a` | トレースされたメッセージのすべての属性、引き数、およびコンテキスト・ スロットを出力します。デフォルトでは、トレース出力へメッセージを出力するには単一 行だけを使用します。
`-o` outfile | トレース出力に使用されるファイル。セッション・トレースの場合、出力先 はtttraceの標準出力です。
`-S` session | トレースするセッション。デフォルトではデフォルト・セッション、つまり `tt_open`が通知するセッションです。
command | 起動し、トレースを行うToolTalkクライアント・コマンド。
-e script | `ttrace`設定として使用されるスクリプト。
-f scriptfile | `tttrace`設定を読み取るファイル。

`tttrace`は、ttsessionへのメッセージ・インタフェースと
`TT_TRACE_SCRIPT`環境変数を使用するToolTalk クライアントとして実行できるようになっています。この変数が設定されると、トレース・ スクリプトに指定されているようにクライアント側トレースをオンにすることを `libtt`に通知します。値の最初の文字が「.」か「/」の場合、その値 は使用するトレース・スクリプトが入っているファイルのパス名として認識されます。その 他の文字の場合は、インライン・トレース・スクリプトとして認識されます。

### トレースされた関数の形式

次は、トレースされたToolTalk関数の例です。

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

#### メッセージ要約形式

`-a`オプションは、次のように１行のメッセージ要約の後に、 メッセージ属性を出力します。

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

#### 状態変更形式

状態の変更は次の形式で示されます。

    old_state => new_state.

#### メッセージ配信形式

配信は次のように示されます。

    Tt_message => procid recipient_procid

TTUG.tttrc.mkr.5は、ディスパッチ・ トレース中に受信するメッセージについて説明しています。

#### ディスパッチ・トレース用の理由

`メッセージ` | `説明`
`tt_message_send` | 送信するメッセージ。
`tt_message_reject` | メッセージが拒否されました。
`tt_message_fail` | メッセージが無視されました。
`tt_message_reply` | メッセージへの応答。
`tt_session_join` | 参加するセッション。
`tt_file_join` | 参加するファイル。
`tt_message_reply` | クライアントが指定の関数を呼び出しました。
`tt_message_send_on_exit` | ttsessionは、`tt_close`を呼び出す前に切り離された クライアントに対してon_exitメッセージをディスパッチしています。
`tt_message_accept` | ttsessionは、ptypeが起動されている間にブロックされたメッセージを ディスパッチしています。起動されたクライアントは、ptypeがブロック解除されることを 示す`tt_message_accept`か`tt_message_reply` のどちらかを呼び出します。
`TT_ERR_PTYPE_START` | ptypeインスタンスがメッセージの受信のために起動されましたが、起動コマ ンドはttsessionに接続される前に終了しました。
`TT_ERR_PROCID` | ttsessionはこの要求に応じて動作中であったクライアントの接続を切りまし た。
`ttsession -> ttsession` | 別のセッションがこのセッションに対してメッセージの受信者を見つけるよ うに求めています。
`ttsession <- ttsession` | 別のセッションがこのセッションで発信したメッセージの更新（たとえば 失敗すること）を求めています。

#### 形式の照合

ディスパッチがトレースされているとき、照合は次の形式のうちの１つで示されま す。

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

パターンまたはシグニチャが次の形式で出力されます。

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

### 例

この節では、tttrace関数の使用例を取り上げます。

#### パターンの登録とパターンの一致通知の送信

パターンを登録し、そのパターンに一致するという通知を送信するには、次のように 入力します。

    % tttrace -a myclientprogram

TTUG.tttrc.mkr.6は、その結果を示し ます。

##### パターンの登録と通知の送信

    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)

ttsessionによるメッセージ・フローの表示を見るには、次のように入力します。

    % tttrace -a

ttsession's view

##### ttsessionによるトレースの表示

    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>

mylientprogramのメッセージ・フローの表示は、 TTUG.tttrc.mkr.7のとおりです。

トレースされた最初のメッセージは、ほとんどの場合`tttrace` が送信した要求へのttsessionによる応答になります。

#### メッセージ・フローのトレース

特定の、デフォルトではないセッション内のメッセージ・フローをトレースするに は、次のように入力します。

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

“01 15303 1342177284 1 0 13691 129.144.153.55 2“は、デフォルトではない 特定のトレースされるセッションです。

“01 15303 1342177284 1 0 13691 129.144.153.55 2“ is the

## ToolTalkトレースのための設定

`tttrace`スクリプトには、ToolTalk呼び出しとメッセージをコン トロールする設定があります。`tttrace`スクリプトは、セミコロンか 復帰改行で区切られたコマンドから成ります。重複している値が設定に指定されると、最後 の値が使用されます。 TTUG.tttrc.mkr.8では、これらのコマンド について説明します。

## tttraceスクリプト・コマンド

`コマンド` | `説明`
`version` n | 使用されている`tttracefile`コマンド構文のバーショ ン。現在のバージョンは1です。
`follow [off | on]` | トレースされたクライアントによってフォークされた、またはトレースされ たセッションで続けて起動されたすべての子についても追跡するかどうか設定します。 デフォルトは`off`です。
`[> | >>]` outfile | トレース出力に使用されるファイル。デフォルトでは、トレースの出力先は 標準エラーです。>と>>の通常のシェル解釈 が適用されます。
`functions` [all | none | func...] | トレースするToolTalk API関数。funcには、シェル・ ワイルドカード文字が入ります。デフォルトは`all`です。
`attributes [all | none]` | `none`（デフォルト）は、トレース出力にメッセージを 出力するとき、単一行だけを使用することを意味します。`all`は、 トレースされたメッセージの属性、引き数、コンテキスト・スロットすべてを出力すること を意味します。
`states [none | edge | deliver | dispatch |` Tt_state`]...` | メッセージをトレースするための状態。`tt_c.h`に定議 されているTt_statesの他に有効な状態は次のとおりで す。 • `none` – メッセージのトレースをすべ て使用不可能にする • `edge` – 最初の状態 (`TT_SENT`)と最後の状態(`TT_HANDLED`と `TT_FAILED`)を入力しているメッセージ • `deliver` – すべての状態の変更と、すべての クライアントの配信 • `dispatch` – 配信およ び一致するように考慮されたすべてのパターン（デフォルト）
`ops` toTrace... `sender_ptypes` toTrace... `handler_ptypes` toTrace... | 表示されたメッセージの属性としてtoTraceを持って いるトレース・メッセージ。toTraceにはシェル・ワイルドカード 文字が入ります。指定のメッセージ属性に対してtoTrace 引き数がない場合、その属性がどんな値を持っていてもメッセージをトレースから除外する ことはありません。