1ttb(3)                     Erlang Module Definition                     ttb(3)
2
3
4

NAME

6       ttb - A base for building trace tools for distributed systems.
7

DESCRIPTION

9       The  Trace  Tool  Builder,  ttb, is a base for building trace tools for
10       distributed systems.
11
12       When using ttb, do not use module dbg in application  Runtime_Tools  in
13       parallel.
14

EXPORTS

16       start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result
17
18              Types:
19
20                 Result = see p/2
21                 Nodes = see tracer/2
22                 Patterns = [tuple()]
23                 FlagSpec = {Procs, Flags}
24                 Proc = see p/2
25                 Flags = see p/2
26                 Opts = see tracer/2
27
28              This  function  is a shortcut allowing to start a trace with one
29              command. Each tuple in Patterns is converted to a list, which in
30              turn is passed to ttb:tpl/2,3,4.
31
32              The call:
33
34              > ttb:start_trace([Node, OtherNode], [{mod, foo, []}, {mod, bar, 2}], {all, call}, [{file, File}, {handler,{fun myhandler/4, S}}]).
35
36              is equivalent to:
37
38              > ttb:start_trace([Node, OtherNode], [{file, File}, {handler,{fun myhandler/4, S}}]), ttb:tpl(mod, foo, []), ttb:tpl(mod, bar, 2, []), ttb:p(all, call).
39
40       tracer() -> Result
41
42              Equivalent to tracer(node()).
43
44       tracer(Shortcut) -> Result
45
46              Types:
47
48                 Shortcut = shell | dbg
49
50              Handy shortcuts for common tracing settings.
51
52              shell  is  equivalent  to tracer(node(),[{file, {local, "ttb"}},
53              shell]).
54
55              dbg is equivalent to tracer(node(),[{shell, only}]).
56
57       tracer(Nodes) -> Result
58
59              Equivalent to tracer(Nodes,[]).
60
61       tracer(Nodes,Opts) -> Result
62
63              Types:
64
65                 Result = {ok, ActivatedNodes} | {error,Reason}
66                 Nodes = atom() | [atom()] | all | existing | new
67                 Opts = Opt | [Opt]
68                 Opt   =   {file,Client}   |   {handler,   FormatHandler}    |
69                 {process_info,PI}  |  shell  |  {shell,  ShellSpec} | {timer,
70                 TimerSpec} | {overload_check,  {MSec,  Module,  Function}}  |
71                 {flush,   MSec}   |   resume   |   {resume,  FetchTimeout}  |
72                 {queue_size, QueueSize}
73                 TimerSpec = MSec | {MSec, StopOpts}
74                 MSec = FetchTimeout = integer()
75                 Module = Function = atom()
76                 StopOpts = see stop/2
77                 Client = File | {local, File}
78                 File = Filename | Wrap
79                 Filename = string()
80                 Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}
81                 FormatHandler = See format/2
82                 PI = true | false
83                 ShellSpec = true | false | only
84                 QueueSize = non_neg_integer()
85
86              Starts a file trace port on all specified nodes and  points  the
87              system tracer for sequential tracing to the same port.
88
89              Options:
90
91                Filename:
92                  The  specified  Filename is prefixed with the node name. De‐
93                  fault Filename is ttb.
94
95                File={wrap,Filename,Size,Count}:
96                  Can be used if the size of the trace logs must  be  limited.
97                  Default values are Size=128*1024 and Count=8.
98
99                Client:
100                  When tracing diskless nodes, ttb must be started from an ex‐
101                  ternal "trace control node" with  disk  access,  and  Client
102                  must be {local, File}. All trace information is then sent to
103                  the trace control node where it is written to file.
104
105                queue_size:
106                  When tracing to shell or {local,File}, an ip trace driver is
107                  used  internally. The ip trace driver has a queue of maximum
108                  QueueSize messages waiting to be delivered.  If  the  driver
109                  cannot  deliver  messages  as fast as they are produced, the
110                  queue size might be exceeded and messages are dropped.  This
111                  parameter  is  optional, and is only useful if many {drop,N}
112                  trace messages are received by the trace handler. It has  no
113                  meaning   if   shell   or  {local,File}  is  not  used.  See
114                  dbg:trace_port/2 for more information  about  the  ip  trace
115                  driver.
116
117                process_info:
118                  Indicates if process information is to be collected. If PI =
119                  true (which is default), each process identifier Pid is  re‐
120                  placed  by a tuple {Pid,ProcessInfo,Node}, where ProcessInfo
121                  is the registered  process  name,  its  globally  registered
122                  name,  or its initial function. To turn off this functional‐
123                  ity, set PI = false.
124
125                {shell, ShellSpec}:
126                  Indicates that trace messages are to be printed on the  con‐
127                  sole  as  they are received by the tracing process. This im‐
128                  plies trace client {local, File}. If ShellSpec is only  (in‐
129                  stead of true), no trace logs are stored.
130
131                shell:
132                  Shortcut for {shell, true}.
133
134                timer:
135                  Indicates  that the trace is to be automatically stopped af‐
136                  ter  MSec  milliseconds.  StopOpts  are  passed  to  command
137                  ttb:stop/2  if  specified  (default  is []). Notice that the
138                  timing is approximate, as delays related to network communi‐
139                  cation are always present. The timer starts after ttb:p/2 is
140                  issued, so you can set up your trace patterns before.
141
142                overload_check:
143                  Allows to enable overload checking on the nodes under trace.
144                  Module:Function(check)  is  performed each MSec millisecond.
145                  If the check returns true, the  tracing  is  disabled  on  a
146                  specified node.
147
148                  Module:Function must be able to handle at least three atoms:
149                  init, check, and stop. init and stop allows you to  initial‐
150                  ize and clean up the check environment.
151
152                  When  a  node  gets  overloaded, it is not possible to issue
153                  ttb:p/2 or any command from the ttb:tp/2,3,4 family,  as  it
154                  would  lead  to  inconsistent tracing state (different trace
155                  specifications on different nodes).
156
157                flush:
158                  Periodically  flushes  all  file  trace  port  clients  (see
159                  dbg:flush_trace_port/1). When enabled, the buffers are freed
160                  each MSec millisecond.  This  option  is  not  allowed  with
161                  {file, {local, File}} tracing.
162
163                {resume, FetchTimeout}:
164                  Enables  the  autoresume feature. When enabled, remote nodes
165                  try to  reconnect  to  the  controlling  node  if  they  are
166                  restarted. The feature requires application Runtime_Tools to
167                  be started (so it has to be present in the .boot scripts  if
168                  the  traced  nodes run with embedded Erlang). If this is not
169                  possible, resume can be performed manually by starting  Run‐
170                  time_Tools remotely using rpc:call/4.
171
172                  ttb  tries to fetch all logs from a reconnecting node before
173                  reinitializing the trace. This must finish within FetchTime‐
174                  out milliseconds or is aborted.
175
176                  By  default, autostart information is stored in a file named
177                  ttb_autostart.bin on each node. If this is not desired  (for
178                  example,  on  diskless  nodes), a custom module handling au‐
179                  tostart information storage and retrieval can be provided by
180                  specifying environment variable ttb_autostart_module for the
181                  application Runtime_Tools. The module must  respond  to  the
182                  following API:
183
184                  write_config(Data) -> ok:
185                    Stores  the provided data for further retrieval. It is im‐
186                    portant to realize that the data storage used must not  be
187                    affected by the node crash.
188
189                  read_config() -> {ok, Data} | {error, Error}:
190                    Retrieves configuration stored with write_config(Data).
191
192                  delete_config() -> ok:
193                    Deletes  configuration stored with write_config(Data). No‐
194                    tice  that  after  this  call  any  subsequent  calls   to
195                    read_config must return {error, Error}.
196
197                  resume implies the default FetchTimeout, which is 10 seconds
198
199       p(Item,Flags) -> Return
200
201              Types:
202
203                 Return = {ok,[{Item,MatchDesc}]}
204                 Items = Item | [Item]
205                 Item  =  pid()  | port() | RegName | {global,GlobalRegName} |
206                 all | processes | ports | existing | existing_processes | ex‐
207                 isting_ports | new | new_processes | new_ports
208                 RegName = atom()
209                 GlobalRegName = term()
210                 Flags = Flag | [Flag]
211
212              Sets  the  specified  trace  flags on the specified processes or
213              ports. Flag timestamp is always turned on.
214
215              See the Reference Manual for module dbg for the  possible  trace
216              flags. Parameter MatchDesc is the same as returned from dbg:p/2.
217
218              Processes  can be specified as registered names, globally regis‐
219              tered names, or process identifiers. Ports can be  specified  as
220              registered  names  or  port identifiers. If a registered name is
221              specified, the flags are set on processes/ports with  this  name
222              on all active nodes.
223
224              Issuing  this  command starts the timer for this trace if option
225              timer is specified with tracer/2.
226
227       tp(Module [, Function [, Arity]], MatchSpec)
228       tp({Module, Function , Arity}, MatchSpec)
229       tpl(Module [, Function [, Arity]], MatchSpec)
230       tpl({Module, Function , Arity}, MatchSpec)
231       ctp()
232       ctp(Module [, Function [, Arity]])
233       ctp({Module, Function, Arity})
234       ctpl()
235       ctpl(Module [, Function [, Arity]])
236       ctpl({Module, Function, Arity})
237       ctpg()
238       ctpg(Module [, Function [, Arity]])
239       ctpg({Module, Function, Arity})
240       tpe(Event,MatchSpec)
241       ctpe(Event)
242
243              These functions are to be used with trace flag call,  send,  and
244              'receive' for setting and clearing trace patterns.
245
246              When  trace  flag  call  is set on a process, function calls are
247              traced on that process if a trace pattern is set for the  called
248              function.
249
250              The send and 'receive' flags enable tracing of all messages sent
251              and received by the process/port. Trace patterns  set  with  tpe
252              may  limit  traced  messages  based  on the message content, the
253              sender, and/or the receiver.
254
255              Trace patterns specify how to trace a function or a  message  by
256              using  match  specifications. Match specifications are described
257              in the ERTS User's Guide.
258
259              These functions are equivalent to the corresponding functions in
260              module dbg, but all calls are stored in the history. The history
261              buffer makes it easy to create  configuration  files;  the  same
262              trace environment can be set up many times, for example, to com‐
263              pare two test runs. It also reduces the amount  of  typing  when
264              using ttb from the Erlang shell.
265
266                tp:
267                  Sets trace patterns on global function calls.
268
269                tpl:
270                  Sets trace patterns on local and global function calls.
271
272                tpe:
273                  Sets trace patterns on messages.
274
275                ctp:
276                  Clears trace patterns on local and global function calls.
277
278                ctpl:
279                  Clears trace patterns on local function calls.
280
281                ctpg:
282                  Clears trace patterns on global function calls.
283
284                ctpe:
285                  Clears trace patterns on messages.
286
287              With tp and tpl, one of the match specification shortcuts can be
288              used (for example, ttb:tp(foo_module, caller)).
289
290              The shortcuts are as follows:
291
292                * return - for [{'_',[],[{return_trace}]}] (report the  return
293                  value from a traced function)
294
295                * caller  -  for  [{'_',[],[{message,{caller}}]}]  (report the
296                  calling function)
297
298                * {codestr,  Str}  -  for  dbg:fun2ms/1  arguments  passed  as
299                  strings (example: "fun(_) -> return_trace() end")
300
301       list_history() -> History
302
303              Types:
304
305                 History = [{N,Func,Args}]
306
307              All calls to ttb is stored in the history. This function returns
308              the current content of the history. Any entry can be  reexecuted
309              with  run_history/1  or  stored  in  a  configuration  file with
310              write_config/2,3.
311
312       run_history(N) -> ok | {error, Reason}
313
314              Types:
315
316                 N = integer() | [integer()]
317
318              Executes the specified entry or entries from the  history  list.
319              To list history, use list_history/0.
320
321       write_config(ConfigFile,Config)
322
323              Equivalent to write_config(ConfigFile,Config,[]).
324
325       write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}
326
327              Types:
328
329                 ConfigFile = string()
330                 Config = all | [integer()] | [{Mod,Func,Args}]
331                 Mod = atom()
332                 Func = atom()
333                 Args = [term()]
334                 Opts = Opt | [Opt]
335                 Opt = append
336
337              Creates  or  extends a configuration file, which can be used for
338              restoring a specific configuration later.
339
340              The contents of the configuration file  can  either  be  fetched
341              from   the   history   or   specified  directly  as  a  list  of
342              {Mod,Func,Args}.
343
344              If the complete history is to be  stored  in  the  configuration
345              file,  Config  must be all. If only a selected number of entries
346              from the history are to be stored, Config must be a list of  in‐
347              tegers pointing out the entries to be stored.
348
349              If  Opts  is not specified or if it is [], ConfigFile is deleted
350              and a new file is created. If Opts = [append], ConfigFile is not
351              deleted. The new information is appended at the end of the file.
352
353       run_config(ConfigFile) -> ok | {error,Reason}
354
355              Types:
356
357                 ConfigFile = string()
358
359              Executes all entries in the specified configuration file. Notice
360              that the history of the last trace is always available  in  file
361              ttb_last_config.
362
363       run_config(ConfigFile,NumList) -> ok | {error,Reason}
364
365              Types:
366
367                 ConfigFile = string()
368                 NumList = [integer()]
369
370              Executes selected entries from the specified configuration file.
371              NumList is a list of integers pointing out the entries to be ex‐
372              ecuted.
373
374              To list the contents of a configuration file, use list_config/1.
375
376              Notice that the history of the last trace is always available in
377              file ttb_last_config.
378
379       list_config(ConfigFile) -> Config | {error,Reason}
380
381              Types:
382
383                 ConfigFile = string()
384                 Config = [{N,Func,Args}]
385
386              Lists all entries in the specified configuration file.
387
388       write_trace_info(Key,Info) -> ok
389
390              Types:
391
392                 Key = term()
393                 Info = Data | fun() -> Data
394                 Data = term()
395
396              File .ti contains {Key,ValueList}  tuples.  This  function  adds
397              Data to the ValueList associated with Key. All information writ‐
398              ten with this function is included in the  call  to  the  format
399              handler.
400
401       seq_trigger_ms() -> MatchSpec
402
403              Equivalent to seq_trigger_ms(all).
404
405       seq_trigger_ms(Flags) -> MatchSpec
406
407              Types:
408
409                 MatchSpec = match_spec()
410                 Flags = all | SeqTraceFlag | [SeqTraceFlag]
411                 SeqTraceFlag = atom()
412
413              A  match  specification  can  turn on or off sequential tracing.
414              This function returns a match specification, which turns on  se‐
415              quential tracing with the specified Flags.
416
417              This  match  specification can be specified as the last argument
418              to tp or tpl. The activated Item then becomes a trigger for  se‐
419              quential  tracing.  This  means  that if the item is called on a
420              process with trace flag call set, the process is  "contaminated"
421              with token seq_trace.
422
423              If Flags = all, all possible flags are set.
424
425              The possible values for SeqTraceFlag are available in seq_trace.
426
427              For  a description of the match_spec() syntax, see section Match
428              Specifications in Erlang in ERTS,  which  explains  the  general
429              match specification "language".
430
431          Note:
432              The system tracer for sequential tracing is automatically initi‐
433              ated by ttb when a trace port is started with ttb:tracer/0,1,2.
434
435
436              An example of how to use function seq_trigger_ms/0,1 follows:
437
438              (tiger@durin)5> ttb:tracer().
439              {ok,[tiger@durin]}
440              (tiger@durin)6> ttb:p(all,call).
441              {ok,{[all],[call]}}
442              (tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
443              {ok,[{matched,1},{saved,1}]}
444              (tiger@durin)8>
445
446              Whenever mod:func(...) is called after this, token seq_trace  is
447              set on the executing process.
448
449       stop()
450
451              Equivalent to stop([]).
452
453       stop(Opts) -> stopped | {stopped, Dir}
454
455              Types:
456
457                 Opts = Opt | [Opt]
458                 Opt  =  nofetch  |  {fetch_dir, Dir} | format | {format, For‐
459                 matOpts} | return_fetch_dir
460                 Dir = string()
461                 FormatOpts = see format/2
462
463              Stops tracing on all nodes. Logs and trace information files are
464              sent  to  the trace control node and stored in a directory named
465              ttb_upload_FileName-Timestamp, where Filename is  the  one  pro‐
466              vided  with  {file, File} during trace setup and Timestamp is of
467              the form yyyymmdd-hhmmss. Even logs from nodes on the  same  ma‐
468              chine as the trace control node are moved to this directory. The
469              history list is saved to a file named ttb_last_config  for  fur‐
470              ther  reference  (as  it is no longer accessible through history
471              and  configuration  management  functions,  like   ttb:list_his‐
472              tory/0).
473
474              Options:
475
476                nofetch:
477                  Indicates  that  trace  logs  are  not to be collected after
478                  tracing is stopped.
479
480                {fetch, Dir}:
481                  Allows specification of the directory to fetch the data  to.
482                  If the directory already exists, an error is thrown.
483
484                format:
485                  Indicates  the  trace  logs to be formatted after tracing is
486                  stopped. All logs in the fetch directory are merged.
487
488                return_fetch_dir:
489                  Indicates the return value to be {stopped, Dir} and not just
490                  stopped. This implies fetch.
491
492       get_et_handler()
493
494              Returns  the  et  handler,  which  can  be used with format/2 or
495              tracer/2.
496
497              Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).
498
499       format(File)
500
501              Equivalent to format(File,[]).
502
503       format(File,Options) -> ok | {error, Reason}
504
505              Types:
506
507                 File = string() | [string()]
508                   This can be the name of a binary log, a list of such  logs,
509                   or  the  name  of a directory containing one or more binary
510                   logs.
511                 Options = Opt | [Opt]
512                 Opt = {out,Out} | {handler,FormatHandler} | disable_sort
513                 Out = standard_io | string()
514                 FormatHandler = {Function, InitialState}
515                 Function = fun(Fd,Trace,TraceInfo,State) -> State
516                 Fd = standard_io | FileDescriptor
517                   File descriptor of the destination file Out.
518                 Trace = tuple()
519                   The trace message. For details, see  the  Reference  Manual
520                   for module erlang.
521                 TraceInfo = [{Key,ValueList}]
522                   Includes  the  keys  flags, client, and node. If handler is
523                   specified as option to the tracer function,  this  is  also
524                   included.  Also,  all  information  written  with  function
525                   write_trace_info/2 is included.
526
527              Reads the specified binary trace log(s). The logs are  processed
528              in the order of their time stamps as long as option disable_sort
529              is not specified.
530
531              If FormatHandler = {Function,InitialState}, Function  is  called
532              for each trace message.
533
534              If FormatHandler = get_et_handler(), et_viewer in application ET
535              is used for presenting the trace log graphically. ttb provides a
536              few different filters that can be selected from menu Filters and
537              scaling in the et_viewer.
538
539              If FormatHandler is not specified, a  default  handler  is  used
540              presenting each trace message as a text line.
541
542              The  state  returned from each call of Function is passed to the
543              next call, even if the next call is to format a message from an‐
544              other log file.
545
546              If  Out  is specified, FormatHandler gets the file descriptor to
547              Out as the first parameter.
548
549              Out is ignored if the et format handler is used.
550
551              Wrap logs can be formatted one by one or all at once. To  format
552              one  of  the wrap logs in a set, specify the exact file name. To
553              format the whole set of wrap logs, specify the name with  *  in‐
554              stead of the wrap count. For examples, see the User's Guide.
555
556
557
558Ericsson AB                      observer 2.14                          ttb(3)
Impressum