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.
93 Default 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
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 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
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 {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 shell:
132 Shortcut for {shell, true}.
133 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 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
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 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 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).
194 Notice 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 |
207 existing_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, tpl, ctp, ctpl, ctpg
228 tpe, ctpe
229 These functions are to be used with trace flag call, send, and
231 'receive' for setting and clearing trace patterns.
232 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 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 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 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 tp:
254 Sets trace patterns on global function calls.
255 tpl:
257 Sets trace patterns on local and global function calls.
258 tpe:
260 Sets trace patterns on messages.
261 ctp:
263 Clears trace patterns on local and global function calls.
264 ctpl:
266 Clears trace patterns on local function calls.
267 ctpg:
269 Clears trace patterns on global function calls.
270 ctpe:
272 Clears trace patterns on messages.
273 With tp and tpl, one of the match specification shortcuts can be
275 used (for example, ttb:tp(foo_module, caller)).
276 The shortcuts are as follows:
278 * return - for [{'_',[],[{return_trace}]}] (report the return
280 value from a traced function)
281 * caller - for [{'_',[],[{message,{caller}}]}] (report the
283 calling function)
284 * {codestr, Str} - for dbg:fun2ms/1 arguments passed as
286 strings (example: "fun(_) -> return_trace() end")
287 list_history() -> History
289 Types:
291 History = [{N,Func,Args}]
293 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 run_history(N) -> ok | {error, Reason}
300 Types:
302 N = integer() | [integer()]
304 Executes the specified entry or entries from the history list.
306 To list history, use list_history/0.
307 write_config(ConfigFile,Config)
309 Equivalent to write_config(ConfigFile,Config,[]).
311 write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}
313 Types:
315 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 Creates or extends a configuration file, which can be used for
325 restoring a specific configuration later.
326 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 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 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 run_config(ConfigFile) -> ok | {error,Reason}
341 Types:
343 ConfigFile = string()
345 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 run_config(ConfigFile,NumList) -> ok | {error,Reason}
351 Types:
353 ConfigFile = string()
355 NumList = [integer()]
356 Executes selected entries from the specified configuration file.
358 NumList is a list of integers pointing out the entries to be
359 executed.
360 To list the contents of a configuration file, use list_config/1.
362 Notice that the history of the last trace is always available in
364 file ttb_last_config.
365 list_config(ConfigFile) -> Config | {error,Reason}
367 Types:
369 ConfigFile = string()
371 Config = [{N,Func,Args}]
372 Lists all entries in the specified configuration file.
374 write_trace_info(Key,Info) -> ok
376 Types:
378 Key = term()
380 Info = Data | fun() -> Data
381 Data = term()
382 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 seq_trigger_ms() -> MatchSpec
389 Equivalent to seq_trigger_ms(all).
391 seq_trigger_ms(Flags) -> MatchSpec
393 Types:
395 MatchSpec = match_spec()
397 Flags = all | SeqTraceFlag | [SeqTraceFlag]
398 SeqTraceFlag = atom()
399 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 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 If Flags = all, all possible flags are set.
411 The possible values for SeqTraceFlag are available in seq_trace.
413 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 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 An example of how to use function seq_trigger_ms/0,1 follows:
424 (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 Whenever mod:func(...) is called after this, token seq_trace is
434 set on the executing process.
435 stop()
437 Equivalent to stop([]).
439 stop(Opts) -> stopped | {stopped, Dir}
441 Types:
443 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 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 Options:
462 nofetch:
464 Indicates that trace logs are not to be collected after
465 tracing is stopped.
466 {fetch, Dir}:
468 Allows specification of the directory to fetch the data to.
469 If the directory already exists, an error is thrown.
470 format:
472 Indicates the trace logs to be formatted after tracing is
473 stopped. All logs in the fetch directory are merged.
474 return_fetch_dir:
476 Indicates the return value to be {stopped, Dir} and not just
477 stopped. This implies fetch.
478 get_et_handler()
480 Returns the et handler, which can be used with format/2 or
482 tracer/2.
483 Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).
485 format(File)
487 Equivalent to format(File,[]).
489 format(File,Options) -> ok | {error, Reason}
491 Types:
493 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 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 If FormatHandler = {Function,InitialState}, Function is called
519 for each trace message.
520 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 If FormatHandler is not specified, a default handler is used
527 presenting each trace message as a text line.
528 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 If Out is specified, FormatHandler gets the file descriptor to
534 Out as the first parameter.
535 Out is ignored if the et format handler is used.
537 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.
542Ericsson AB observer 2.9 ttb(3)