1ttb(3) Erlang Module Definition ttb(3)
2
6 ttb - A base for building trace tools for distributed systems.
7
9 The Trace Tool Builder, ttb, is a base for building trace tools for
10 distributed systems.
11 When using ttb, do not use module dbg in application Runtime_Tools in
13 parallel.
14
16 start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result
17 Types:
19 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 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 The call:
33 > ttb:start_trace([Node, OtherNode], [{mod, foo, []}, {mod, bar, 2}], {all, call}, [{file, File}, {handler,{fun myhandler/4, S}}]).
35 is equivalent to:
37 > 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 tracer() -> Result
41 Equivalent to tracer(node()).
43 tracer(Shortcut) -> Result
45 Types:
47 Shortcut = shell | dbg
49 Handy shortcuts for common tracing settings.
51 shell is equivalent to tracer(node(),[{file, {local, "ttb"}},
53 shell]).
54 dbg is equivalent to tracer(node(),[{shell, only}]).
56 tracer(Nodes) -> Result
58 Equivalent to tracer(Nodes,[]).
60 tracer(Nodes,Opts) -> Result
62 Types:
64 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 Starts a file trace port on all specified nodes and points the
87 system tracer for sequential tracing to the same port.
88 Options:
90 Filename:
92 The specified Filename is prefixed with the node name. De‐
93 fault Filename is ttb.
94 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 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 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 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 {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 shell:
132 Shortcut for {shell, true}.
133 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 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 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 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 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 {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 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 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 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 read_config() -> {ok, Data} | {error, Error}:
190 Retrieves configuration stored with write_config(Data).
191 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 resume implies the default FetchTimeout, which is 10 seconds
198 p(Item,Flags) -> Return
200 Types:
202 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 Sets the specified trace flags on the specified processes or
213 ports. Flag timestamp is always turned on.
214 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 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 Issuing this command starts the timer for this trace if option
225 timer is specified with tracer/2.
226 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 These functions are to be used with trace flag call, send, and
244 'receive' for setting and clearing trace patterns.
245 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 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 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 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 tp:
267 Sets trace patterns on global function calls.
268 tpl:
270 Sets trace patterns on local and global function calls.
271 tpe:
273 Sets trace patterns on messages.
274 ctp:
276 Clears trace patterns on local and global function calls.
277 ctpl:
279 Clears trace patterns on local function calls.
280 ctpg:
282 Clears trace patterns on global function calls.
283 ctpe:
285 Clears trace patterns on messages.
286 With tp and tpl, one of the match specification shortcuts can be
288 used (for example, ttb:tp(foo_module, caller)).
289 The shortcuts are as follows:
291 * return - for [{'_',[],[{return_trace}]}] (report the return
293 value from a traced function)
294 * caller - for [{'_',[],[{message,{caller}}]}] (report the
296 calling function)
297 * {codestr, Str} - for dbg:fun2ms/1 arguments passed as
299 strings (example: "fun(_) -> return_trace() end")
300 list_history() -> History
302 Types:
304 History = [{N,Func,Args}]
306 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 run_history(N) -> ok | {error, Reason}
313 Types:
315 N = integer() | [integer()]
317 Executes the specified entry or entries from the history list.
319 To list history, use list_history/0.
320 write_config(ConfigFile,Config)
322 Equivalent to write_config(ConfigFile,Config,[]).
324 write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}
326 Types:
328 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 Creates or extends a configuration file, which can be used for
338 restoring a specific configuration later.
339 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 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 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 run_config(ConfigFile) -> ok | {error,Reason}
354 Types:
356 ConfigFile = string()
358 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 run_config(ConfigFile,NumList) -> ok | {error,Reason}
364 Types:
366 ConfigFile = string()
368 NumList = [integer()]
369 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 To list the contents of a configuration file, use list_config/1.
375 Notice that the history of the last trace is always available in
377 file ttb_last_config.
378 list_config(ConfigFile) -> Config | {error,Reason}
380 Types:
382 ConfigFile = string()
384 Config = [{N,Func,Args}]
385 Lists all entries in the specified configuration file.
387 write_trace_info(Key,Info) -> ok
389 Types:
391 Key = term()
393 Info = Data | fun() -> Data
394 Data = term()
395 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 seq_trigger_ms() -> MatchSpec
402 Equivalent to seq_trigger_ms(all).
404 seq_trigger_ms(Flags) -> MatchSpec
406 Types:
408 MatchSpec = match_spec()
410 Flags = all | SeqTraceFlag | [SeqTraceFlag]
411 SeqTraceFlag = atom()
412 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 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 If Flags = all, all possible flags are set.
424 The possible values for SeqTraceFlag are available in seq_trace.
426 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 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 An example of how to use function seq_trigger_ms/0,1 follows:
437 (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 Whenever mod:func(...) is called after this, token seq_trace is
447 set on the executing process.
448 stop()
450 Equivalent to stop([]).
452 stop(Opts) -> stopped | {stopped, Dir}
454 Types:
456 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 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 Options:
475 nofetch:
477 Indicates that trace logs are not to be collected after
478 tracing is stopped.
479 {fetch, Dir}:
481 Allows specification of the directory to fetch the data to.
482 If the directory already exists, an error is thrown.
483 format:
485 Indicates the trace logs to be formatted after tracing is
486 stopped. All logs in the fetch directory are merged.
487 return_fetch_dir:
489 Indicates the return value to be {stopped, Dir} and not just
490 stopped. This implies fetch.
491 get_et_handler()
493 Returns the et handler, which can be used with format/2 or
495 tracer/2.
496 Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).
498 format(File)
500 Equivalent to format(File,[]).
502 format(File,Options) -> ok | {error, Reason}
504 Types:
506 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 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 If FormatHandler = {Function,InitialState}, Function is called
532 for each trace message.
533 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 If FormatHandler is not specified, a default handler is used
540 presenting each trace message as a text line.
541 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 If Out is specified, FormatHandler gets the file descriptor to
547 Out as the first parameter.
548 Out is ignored if the et format handler is used.
550 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.
555Ericsson AB observer 2.11.1 ttb(3)