資訊傳輸的循序追蹤。

循序追蹤可以追蹤因一次初始資訊傳輸而在不同程序之間產生的資訊流。循序追蹤與 Erlang 中由 erlang:trace/3 BIF 控制的普通追蹤是獨立的。有關循序追蹤是什麼以及如何使用它的更多資訊，請參閱 循序追蹤 章節。

seq_trace 提供控制循序追蹤所有方面的功能。有啟用、停用、檢查和收集追蹤輸出的功能。

傳送至系統追蹤器的追蹤訊息

訊息格式如下列之一，取決於追蹤令牌的 timestamp 旗標是否設定為 true 或 false

{seq_trace, Label, SeqTraceInfo, TimeStamp}

或

{seq_trace, Label, SeqTraceInfo}

其中

Label = int()
TimeStamp = {Seconds, Milliseconds, Microseconds}
  Seconds = Milliseconds = Microseconds = int()

SeqTraceInfo 可以具有以下格式

• {send, Serial, From, To, Message} - 當一個程序 From，其追蹤令牌旗標 send 設定為 true 時，已傳送資訊時使用。To 可以是程序識別符、節點上註冊的名稱表示為 {NameAtom, NodeAtom}，或表示為原子符號的節點名稱。From 可以是程序識別符或表示為原子符號的節點名稱。Message 包含在此資訊傳輸中傳遞的資訊。如果傳輸是透過訊息傳遞完成的，則它是實際的訊息。

• {'receive', Serial, From, To, Message} - 當一個程序 To 接收到追蹤令牌的資訊，其旗標 'receive' 設定為 true 時使用。To 可以是程序識別符或表示為原子符號的節點名稱。From 可以是程序識別符或表示為原子符號的節點名稱。Message 包含在此資訊傳輸中傳遞的資訊。如果傳輸是透過訊息傳遞完成的，則它是實際的訊息。

• {print, Serial, From, _, Info} - 當一個程序 From 呼叫 seq_trace:print(Label, TraceInfo) 並且有一個追蹤令牌，其旗標 print 設定為 true，並且 label 設定為 Label 時使用。

Serial 是一個元組 {PreviousSerial, ThisSerial}，其中

• 整數 PreviousSerial 表示在最後接收的攜帶追蹤令牌的資訊中傳遞的序列計數器。如果該程序是新循序追蹤中的第一個程序，則 PreviousSerial 會設定為程序內部「追蹤時鐘」的值。
• 整數 ThisSerial 是程序在傳出訊息上設定的序列計數器。它基於程序內部「追蹤時鐘」，該時鐘在附加到訊息中的追蹤令牌之前遞增一。

循序追蹤

循序追蹤是一種追蹤不同本地或遠端程序之間資訊傳輸序列的方式，其中該序列是由單一傳輸啟動的。典型的資訊傳輸是在兩個程序之間傳遞的普通 Erlang 訊息，但是資訊也以其他方式傳輸。簡而言之，它的工作方式如下

每個程序都有一個追蹤令牌，它可以是空的或非空的。當非空時，追蹤令牌可以被視為元組 {Label, Flags, Serial, From}。當資訊在程序之間傳遞時，追蹤令牌會被不可見地傳遞。在大多數情況下，資訊是在程序之間的普通訊息中傳遞的，但是資訊也可以透過其他方式在程序之間傳遞。例如，透過產生一個新程序。兩個程序之間的資訊傳輸由一個發送事件和一個接收事件表示，無論它是如何傳遞的。

要啟動循序追蹤，使用者必須顯式設定將在序列中發送第一個資訊的程序的追蹤令牌。

每次程序接收到資訊時都會設定程序的追蹤令牌。這通常是在程序根據接收到的訊息攜帶的追蹤令牌（無論是否為空）在 receive 陳述式中匹配訊息時。

在每個 Erlang 節點上，可以將一個程序設定為系統追蹤器。每次傳送或接收帶有追蹤令牌的資訊時，此程序都會接收追蹤訊息（如果追蹤令牌旗標 send 或 'receive' 設定）。然後，系統追蹤器可以列印每個追蹤事件、將其寫入檔案或任何合適的操作。

注意

系統追蹤器僅接收在 Erlang 節點內本地發生的那些追蹤事件。為了獲取涉及許多 Erlang 節點上的程序的循序追蹤的完整畫面，必須合併（離線）每個涉及的節點上的系統追蹤器的輸出。

以下各節描述了循序追蹤及其最基本的概念。

不同的資訊傳輸

資訊以許多不同的方式在程序之間流動。並非所有資訊流都將被循序追蹤覆蓋。一個範例是透過 ETS 表格傳遞的資訊。以下是循序追蹤涵蓋的資訊路徑列表

• 訊息傳遞 - 在 Erlang 程序之間傳遞的所有普通訊息。

• 退出訊號 - 退出訊號表示為 {'EXIT', Pid, Reason} 元組。

• 程序產生 - 程序產生表示為多個資訊傳輸。至少一個產生請求和一個產生回覆。實際的資訊傳輸量取決於產生的類型，並且在將來的實作中也可能會改變。請注意，這或多或少是一個您正在窺視的內部協定。產生請求將表示為一個元組，其第一個元素包含原子符號 spawn_request，但這或多或少是您可以依賴的全部內容。

注意

如果您在系統上執行普通的 send 或 receive 追蹤，則只會看到普通的訊息傳遞，而不會看到上面列出的其他資訊傳輸。

注意

當發送事件和相應的接收事件並非都對應於普通的 Erlang 訊息時，追蹤訊息的 Message 部分可能不相同。這是因為在產生追蹤訊息時並非所有資訊都一定可用。

追蹤令牌

每個程序都有一個當前的追蹤令牌，該令牌在建立程序時從父程序「不可見地」傳遞。

程序的當前令牌以下列兩種方式之一設定

• 透過程序本身，透過呼叫 seq_trace:set_token/1,2 明確設定
• 當接收到資訊時。這通常是在接收表示式中比對接收到的訊息時，但也當以其他方式接收到資訊時。

在這兩種情況下，都會設定當前令牌。特別是，如果接收到的訊息的令牌為空，則程序的當前令牌會設定為空。

追蹤令牌包含標籤和一組旗標。標籤和旗標都在上述兩種替代方案中設定。

序列

追蹤令牌包含一個名為 serial 的元件。它由兩個整數組成，Previous 和 Current。目的是在追蹤序列中唯一識別每個追蹤事件，並按時間順序和不同的分支（如果有的話）對訊息進行排序。

更新 Serial 的演算法可以描述如下

讓每個程序都有兩個計數器，prev_cnt 和 curr_cnt，當在追蹤序列之外建立程序時，它們都設定為 0。計數器在以下情況下更新

• 當程序即將將資訊傳遞給另一個程序且追蹤令牌不為空時。 這通常在發送訊息時發生，但也例如在產生另一個程序時。

  讓追蹤令牌的序列為 tprev 和 tcurr。

  curr_cnt := curr_cnt + 1
  tprev := prev_cnt
  tcurr := curr_cnt

  然後，具有 tprev 和 tcurr 的追蹤令牌會與傳遞給另一個程序的資訊一起傳遞。

• 當程序呼叫 seq_trace:print(Label, Info)，Label 符合追蹤令牌的標籤部分，並且追蹤令牌的列印旗標為 true 時。

  演算法與上述發送的演算法相同。

• 當接收到的資訊也包含非空的追蹤令牌時。例如，當在 receive 表示式中比對出訊息時，或當產生新程序時。

  程序追蹤令牌設定為訊息中的追蹤令牌。

  讓追蹤令牌的序列為 tprev 和 tcurr。

  if (curr_cnt < tcurr )
     curr_cnt := tcurr
  prev_cnt := tcurr

每次程序參與循序追蹤時，都會遞增程序的 curr_cnt。如果程序存在很長時間並參與了許多循序追蹤，則計數器可能會達到其上限（27 位）。如果計數器溢位，則無法使用追蹤事件的排序序列。為了防止計數器在循序追蹤的中途溢位，可以呼叫函式 seq_trace:reset_trace/0 以重置 Erlang 節點中所有程序的 prev_cnt 和 curr_cnt。此函式還會將程序及其訊息佇列中的所有追蹤令牌設定為空，從而停止所有正在進行的循序追蹤。

效能考量

只要未啟動追蹤，啟用循序追蹤的系統的效能下降可以忽略不計。啟動追蹤後，每個追蹤的訊息都會產生額外的成本，但是所有其他訊息都不受影響。

連接埠

循序追蹤不會跨連接埠執行。

如果使用者因為某些原因想要將追蹤令牌傳遞到連接埠，則必須在控制該連接埠的程式碼中手動完成。控制連接埠的程序必須檢查適當的循序追蹤設定（從 seq_trace:get_token/1 取得），並將追蹤資訊包含在傳送到各自連接埠的訊息資料中。

同樣地，對於從連接埠接收到的訊息，連接埠控制器必須檢索追蹤特定的資訊，並透過呼叫 seq_trace:set_token/2 來設定適當的循序追蹤標誌。

分散式

節點之間的循序追蹤是以透明方式執行。這也適用於使用 Erl_Interface 建構的 C 節點。使用 Erl_Interface 建構的 C 節點僅維護一個追蹤令牌，這表示從循序追蹤的角度來看，該 C 節點看起來像是一個程序。

使用範例

此範例概略說明了如何使用新的基本元件以及它產生的輸出類型。

假設您有一個起始程序，其 Pid == <0.30.0>，如下所示：

-module(seqex).
-compile(export_all).

loop(Port) ->
    receive
        {Port,Message} ->
            seq_trace:set_token(label,17),
            seq_trace:set_token('receive',true),
            seq_trace:set_token(print,true),
            seq_trace:print(17,"**** Trace Started ****"),
            call_server ! {self(),the_message};
        {ack,Ack} ->
            ok
    end,
    loop(Port).

以及一個已註冊的程序 call_server，其 Pid == <0.31.0>，如下所示：

loop() ->
    receive
        {PortController,Message} ->
            Ack = {received, Message},
            seq_trace:print(17,"We are here now"),
            PortController ! {ack,Ack}
    end,
    loop().

系統的 sequential_tracer 可能的輸出如下：

17:<0.30.0> Info {0,1} WITH
"**** Trace Started ****"
17:<0.31.0> Received {0,2} FROM <0.30.0> WITH
{<0.30.0>,the_message}
17:<0.31.0> Info {2,3} WITH
"We are here now"
17:<0.30.0> Received {2,4} FROM <0.31.0> WITH
{ack,{received,the_message}}

產生此輸出的系統追蹤器程序的實作可能如下所示：

tracer() ->
    receive
        {seq_trace,Label,TraceInfo} ->
           print_trace(Label,TraceInfo,false);
        {seq_trace,Label,TraceInfo,Ts} ->
           print_trace(Label,TraceInfo,Ts);
        _Other -> ignore
    end,
    tracer().

print_trace(Label,TraceInfo,false) ->
    io:format("~p:",[Label]),
    print_trace(TraceInfo);
print_trace(Label,TraceInfo,Ts) ->
    io:format("~p ~p:",[Label,Ts]),
    print_trace(TraceInfo).

print_trace({print,Serial,From,_,Info}) ->
    io:format("~p Info ~p WITH~n~p~n", [From,Serial,Info]);
print_trace({'receive',Serial,From,To,Message}) ->
    io:format("~p Received ~p FROM ~p WITH~n~p~n",
              [To,Serial,From,Message]);
print_trace({send,Serial,From,To,Message}) ->
    io:format("~p Sent ~p TO ~p WITH~n~p~n",
              [From,Serial,To,Message]).

建立執行此追蹤器函數並將該程序設定為系統追蹤器的程式碼可能如下所示：

start() ->
    Pid = spawn(?MODULE,tracer,[]),
    seq_trace:set_system_tracer(Pid), % set Pid as the system tracer
    ok.

透過像 test/0 這樣的函數，可以啟動整個範例：

test() ->
    P = spawn(?MODULE, loop, [port]),
    register(call_server, spawn(?MODULE, loop, [])),
    start(),
    P ! {port,message}.