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.
93                  Default 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
101                  external "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
120                  replaced  by  a tuple {Pid,ProcessInfo,Node}, where Process‐
121                  Info 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
128                  implies trace client {local, File}.  If  ShellSpec  is  only
129                  (instead 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
136                  after 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
179                  autostart information storage and retrieval can be  provided
180                  by  specifying environment variable ttb_autostart_module for
181                  the application Runtime_Tools. The module  must  respond  to
182                  the following API:
183
184                  write_config(Data) -> ok:
185                    Stores  the  provided  data  for  further retrieval. It is
186                    important to realize that the data storage used  must  not
187                    be 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).
194                    Notice 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  |
207                 existing_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, tpl, ctp, ctpl, ctpg
228       tpe, ctpe
229
230              These functions are to be used with trace flag call,  send,  and
231              'receive' for setting and clearing trace patterns.
232
233              When  trace  flag  call  is set on a process, function calls are
234              traced on that process if a trace pattern is set for the  called
235              function.
236
237              The send and 'receive' flags enable tracing of all messages sent
238              and received by the process/port. Trace patterns  set  with  tpe
239              may  limit  traced  messages  based  on the message content, the
240              sender, and/or the receiver.
241
242              Trace patterns specify how to trace a function or a  message  by
243              using  match  specifications. Match specifications are described
244              in the ERTS User's Guide.
245
246              These functions are equivalent to the corresponding functions in
247              module dbg, but all calls are stored in the history. The history
248              buffer makes it easy to create  configuration  files;  the  same
249              trace environment can be set up many times, for example, to com‐
250              pare two test runs. It also reduces the amount  of  typing  when
251              using ttb from the Erlang shell.
252
253                tp:
254                  Sets trace patterns on global function calls.
255
256                tpl:
257                  Sets trace patterns on local and global function calls.
258
259                tpe:
260                  Sets trace patterns on messages.
261
262                ctp:
263                  Clears trace patterns on local and global function calls.
264
265                ctpl:
266                  Clears trace patterns on local function calls.
267
268                ctpg:
269                  Clears trace patterns on global function calls.
270
271                ctpe:
272                  Clears trace patterns on messages.
273
274              With tp and tpl, one of the match specification shortcuts can be
275              used (for example, ttb:tp(foo_module, caller)).
276
277              The shortcuts are as follows:
278
279                * return - for [{'_',[],[{return_trace}]}] (report the  return
280                  value from a traced function)
281
282                * caller  -  for  [{'_',[],[{message,{caller}}]}]  (report the
283                  calling function)
284
285                * {codestr,  Str}  -  for  dbg:fun2ms/1  arguments  passed  as
286                  strings (example: "fun(_) -> return_trace() end")
287
288       list_history() -> History
289
290              Types:
291
292                 History = [{N,Func,Args}]
293
294              All calls to ttb is stored in the history. This function returns
295              the current content of the history. Any entry can be  reexecuted
296              with  run_history/1  or  stored  in  a  configuration  file with
297              write_config/2,3.
298
299       run_history(N) -> ok | {error, Reason}
300
301              Types:
302
303                 N = integer() | [integer()]
304
305              Executes the specified entry or entries from the  history  list.
306              To list history, use list_history/0.
307
308       write_config(ConfigFile,Config)
309
310              Equivalent to write_config(ConfigFile,Config,[]).
311
312       write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}
313
314              Types:
315
316                 ConfigFile = string()
317                 Config = all | [integer()] | [{Mod,Func,Args}]
318                 Mod = atom()
319                 Func = atom()
320                 Args = [term()]
321                 Opts = Opt | [Opt]
322                 Opt = append
323
324              Creates  or  extends a configuration file, which can be used for
325              restoring a specific configuration later.
326
327              The contents of the configuration file  can  either  be  fetched
328              from   the   history   or   specified  directly  as  a  list  of
329              {Mod,Func,Args}.
330
331              If the complete history is to be  stored  in  the  configuration
332              file,  Config  must be all. If only a selected number of entries
333              from the history are to be stored, Config  must  be  a  list  of
334              integers pointing out the entries to be stored.
335
336              If  Opts  is not specified or if it is [], ConfigFile is deleted
337              and a new file is created. If Opts = [append], ConfigFile is not
338              deleted. The new information is appended at the end of the file.
339
340       run_config(ConfigFile) -> ok | {error,Reason}
341
342              Types:
343
344                 ConfigFile = string()
345
346              Executes all entries in the specified configuration file. Notice
347              that the history of the last trace is always available  in  file
348              ttb_last_config.
349
350       run_config(ConfigFile,NumList) -> ok | {error,Reason}
351
352              Types:
353
354                 ConfigFile = string()
355                 NumList = [integer()]
356
357              Executes selected entries from the specified configuration file.
358              NumList is a list of integers pointing out  the  entries  to  be
359              executed.
360
361              To list the contents of a configuration file, use list_config/1.
362
363              Notice that the history of the last trace is always available in
364              file ttb_last_config.
365
366       list_config(ConfigFile) -> Config | {error,Reason}
367
368              Types:
369
370                 ConfigFile = string()
371                 Config = [{N,Func,Args}]
372
373              Lists all entries in the specified configuration file.
374
375       write_trace_info(Key,Info) -> ok
376
377              Types:
378
379                 Key = term()
380                 Info = Data | fun() -> Data
381                 Data = term()
382
383              File .ti contains {Key,ValueList}  tuples.  This  function  adds
384              Data to the ValueList associated with Key. All information writ‐
385              ten with this function is included in the  call  to  the  format
386              handler.
387
388       seq_trigger_ms() -> MatchSpec
389
390              Equivalent to seq_trigger_ms(all).
391
392       seq_trigger_ms(Flags) -> MatchSpec
393
394              Types:
395
396                 MatchSpec = match_spec()
397                 Flags = all | SeqTraceFlag | [SeqTraceFlag]
398                 SeqTraceFlag = atom()
399
400              A  match  specification  can  turn on or off sequential tracing.
401              This function returns a  match  specification,  which  turns  on
402              sequential tracing with the specified Flags.
403
404              This  match  specification can be specified as the last argument
405              to tp or tpl. The activated Item  then  becomes  a  trigger  for
406              sequential  tracing.  This means that if the item is called on a
407              process with trace flag call set, the process is  "contaminated"
408              with token seq_trace.
409
410              If Flags = all, all possible flags are set.
411
412              The possible values for SeqTraceFlag are available in seq_trace.
413
414              For  a description of the match_spec() syntax, see section Match
415              Specifications in Erlang in ERTS,  which  explains  the  general
416              match specification "language".
417
418          Note:
419              The system tracer for sequential tracing is automatically initi‐
420              ated by ttb when a trace port is started with ttb:tracer/0,1,2.
421
422
423              An example of how to use function seq_trigger_ms/0,1 follows:
424
425              (tiger@durin)5> ttb:tracer().
426              {ok,[tiger@durin]}
427              (tiger@durin)6> ttb:p(all,call).
428              {ok,{[all],[call]}}
429              (tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
430              {ok,[{matched,1},{saved,1}]}
431              (tiger@durin)8>
432
433              Whenever mod:func(...) is called after this, token seq_trace  is
434              set on the executing process.
435
436       stop()
437
438              Equivalent to stop([]).
439
440       stop(Opts) -> stopped | {stopped, Dir}
441
442              Types:
443
444                 Opts = Opt | [Opt]
445                 Opt  =  nofetch  |  {fetch_dir, Dir} | format | {format, For‐
446                 matOpts} | return_fetch_dir
447                 Dir = string()
448                 FormatOpts = see format/2
449
450              Stops tracing on all nodes. Logs and trace information files are
451              sent  to  the trace control node and stored in a directory named
452              ttb_upload_FileName-Timestamp, where Filename is  the  one  pro‐
453              vided  with  {file, File} during trace setup and Timestamp is of
454              the form yyyymmdd-hhmmss. Even  logs  from  nodes  on  the  same
455              machine  as  the trace control node are moved to this directory.
456              The history list is saved to a file  named  ttb_last_config  for
457              further reference (as it is no longer accessible through history
458              and  configuration  management  functions,  like   ttb:list_his‐
459              tory/0).
460
461              Options:
462
463                nofetch:
464                  Indicates  that  trace  logs  are  not to be collected after
465                  tracing is stopped.
466
467                {fetch, Dir}:
468                  Allows specification of the directory to fetch the data  to.
469                  If the directory already exists, an error is thrown.
470
471                format:
472                  Indicates  the  trace  logs to be formatted after tracing is
473                  stopped. All logs in the fetch directory are merged.
474
475                return_fetch_dir:
476                  Indicates the return value to be {stopped, Dir} and not just
477                  stopped. This implies fetch.
478
479       get_et_handler()
480
481              Returns  the  et  handler,  which  can  be used with format/2 or
482              tracer/2.
483
484              Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).
485
486       format(File)
487
488              Equivalent to format(File,[]).
489
490       format(File,Options) -> ok | {error, Reason}
491
492              Types:
493
494                 File = string() | [string()]
495                   This can be the name of a binary log, a list of such  logs,
496                   or  the  name  of a directory containing one or more binary
497                   logs.
498                 Options = Opt | [Opt]
499                 Opt = {out,Out} | {handler,FormatHandler} | disable_sort
500                 Out = standard_io | string()
501                 FormatHandler = {Function, InitialState}
502                 Function = fun(Fd,Trace,TraceInfo,State) -> State
503                 Fd = standard_io | FileDescriptor
504                   File descriptor of the destination file Out.
505                 Trace = tuple()
506                   The trace message. For details, see  the  Reference  Manual
507                   for module erlang.
508                 TraceInfo = [{Key,ValueList}]
509                   Includes  the  keys  flags, client, and node. If handler is
510                   specified as option to the tracer function,  this  is  also
511                   included.  Also,  all  information  written  with  function
512                   write_trace_info/2 is included.
513
514              Reads the specified binary trace log(s). The logs are  processed
515              in the order of their time stamps as long as option disable_sort
516              is not specified.
517
518              If FormatHandler = {Function,InitialState}, Function  is  called
519              for each trace message.
520
521              If FormatHandler = get_et_handler(), et_viewer in application ET
522              is used for presenting the trace log graphically. ttb provides a
523              few different filters that can be selected from menu Filters and
524              scaling in the et_viewer.
525
526              If FormatHandler is not specified, a  default  handler  is  used
527              presenting each trace message as a text line.
528
529              The  state  returned from each call of Function is passed to the
530              next call, even if the next call is to  format  a  message  from
531              another log file.
532
533              If  Out  is specified, FormatHandler gets the file descriptor to
534              Out as the first parameter.
535
536              Out is ignored if the et format handler is used.
537
538              Wrap logs can be formatted one by one or all at once. To  format
539              one  of  the wrap logs in a set, specify the exact file name. To
540              format the whole set of wrap  logs,  specify  the  name  with  *
541              instead of the wrap count. For examples, see the User's Guide.
542
543
544
545Ericsson AB                      observer 2.9                           ttb(3)
Impressum