Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ttb(3)			   Erlang Module Definition			ttb(3)

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

       The  Trace  Tool	 Builder,  ttb,	is a base for building trace tools for
       distributed systems.

       When using ttb, do not use module dbg in	application  Runtime_Tools  in

       start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result


		 Result	= see p/2
		 Nodes = see tracer/2
		 Patterns = [tuple()]
		 FlagSpec = {Procs, Flags}
		 Proc =	see p/2
		 Flags = see p/2
		 Opts =	see tracer/2

	      This  function  is a shortcut allowing to	start a	trace with one
	      command. Each tuple in Patterns is converted to a	list, which in
	      turn is passed to	ttb:tpl/2,3,4.

	      The call:

	      >	ttb:start_trace([Node, OtherNode], [{mod, foo, []}, {mod, bar, 2}], {all, call}, [{file, File},	{handler,{fun myhandler/4, S}}]).

	      is equivalent to:

	      >	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).

       tracer()	-> Result

	      Equivalent to tracer(node()).

       tracer(Shortcut)	-> Result


		 Shortcut = shell | dbg

	      Handy shortcuts for common tracing settings.

	      shell  is	 equivalent  to	tracer(node(),[{file, {local, "ttb"}},

	      dbg is equivalent	to tracer(node(),[{shell, only}]).

       tracer(Nodes) ->	Result

	      Equivalent to tracer(Nodes,[]).

       tracer(Nodes,Opts) -> Result


		 Result	= {ok, ActivatedNodes} | {error,Reason}
		 Nodes = atom()	| [atom()] | all | existing | new
		 Opts =	Opt | [Opt]
		 Opt   =   {file,Client}   |   {handler,   FormatHandler}    |
		 {process_info,PI}  |  shell  |	 {shell,  ShellSpec} | {timer,
		 TimerSpec} | {overload_check,	{MSec,	Module,	 Function}}  |
		 {flush,   MSec}   |   resume	|   {resume,  FetchTimeout}  |
		 {queue_size, QueueSize}
		 TimerSpec = MSec | {MSec, StopOpts}
		 MSec =	FetchTimeout = integer()
		 Module	= Function = atom()
		 StopOpts = see	stop/2
		 Client	= File | {local, File}
		 File =	Filename | Wrap
		 Filename = string()
		 Wrap =	{wrap,Filename}	| {wrap,Filename,Size,Count}
		 FormatHandler = See format/2
		 PI = true | false
		 ShellSpec = true | false | only
		 QueueSize = non_neg_integer()

	      Starts a file trace port on all specified	nodes and  points  the
	      system tracer for	sequential tracing to the same port.


		  The  specified  Filename is prefixed with the	node name. De-
		  fault	Filename is ttb.

		  Can be used if the size of the trace logs must  be  limited.
		  Default values are Size=128*1024 and Count=8.

		  When tracing diskless	nodes, ttb must	be started from	an ex-
		  ternal "trace	control	node" with  disk  access,  and	Client
		  must be {local, File}. All trace information is then sent to
		  the trace control node where it is written to	file.

		  When tracing to shell	or {local,File}, an ip trace driver is
		  used	internally. The	ip trace driver	has a queue of maximum
		  QueueSize messages waiting to	be delivered.  If  the	driver
		  cannot  deliver  messages  as	fast as	they are produced, the
		  queue	size might be exceeded and messages are	dropped.  This
		  parameter  is	 optional, and is only useful if many {drop,N}
		  trace	messages are received by the trace handler. It has  no
		  meaning   if	 shell	 or  {local,File}  is  not  used.  See
		  dbg:trace_port/2 for more information	 about	the  ip	 trace

		  Indicates if process information is to be collected. If PI =
		  true (which is default), each	process	identifier Pid is  re-
		  placed  by a tuple {Pid,ProcessInfo,Node}, where ProcessInfo
		  is the registered  process  name,  its  globally  registered
		  name,	 or its	initial	function. To turn off this functional-
		  ity, set PI =	false.

		{shell,	ShellSpec}:
		  Indicates that trace messages	are to be printed on the  con-
		  sole	as  they are received by the tracing process. This im-
		  plies	trace client {local, File}. If ShellSpec is only  (in-
		  stead	of true), no trace logs	are stored.

		  Shortcut for {shell, true}.

		  Indicates  that the trace is to be automatically stopped af-
		  ter  MSec  milliseconds.  StopOpts  are  passed  to  command
		  ttb:stop/2  if  specified  (default  is []). Notice that the
		  timing is approximate, as delays related to network communi-
		  cation are always present. The timer starts after ttb:p/2 is
		  issued, so you can set up your trace patterns	before.

		  Allows to enable overload checking on	the nodes under	trace.
		  Module:Function(check)  is  performed	each MSec millisecond.
		  If the check returns true, the  tracing  is  disabled	 on  a
		  specified node.

		  Module:Function must be able to handle at least three	atoms:
		  init,	check, and stop. init and stop allows you to  initial-
		  ize and clean	up the check environment.

		  When	a  node	 gets  overloaded, it is not possible to issue
		  ttb:p/2 or any command from the ttb:tp/2,3,4 family,	as  it
		  would	 lead  to  inconsistent	tracing	state (different trace
		  specifications on different nodes).

		  Periodically	flushes	 all  file  trace  port	 clients  (see
		  dbg:flush_trace_port/1). When	enabled, the buffers are freed
		  each MSec millisecond.  This	option	is  not	 allowed  with
		  {file, {local, File}}	tracing.

		{resume, FetchTimeout}:
		  Enables  the	autoresume feature. When enabled, remote nodes
		  try to  reconnect  to	 the  controlling  node	 if  they  are
		  restarted. The feature requires application Runtime_Tools to
		  be started (so it has	to be present in the .boot scripts  if
		  the  traced  nodes run with embedded Erlang).	If this	is not
		  possible, resume can be performed manually by	starting  Run-
		  time_Tools remotely using rpc:call/4.

		  ttb  tries to	fetch all logs from a reconnecting node	before
		  reinitializing the trace. This must finish within FetchTime-
		  out milliseconds or is aborted.

		  By  default, autostart information is	stored in a file named
		  ttb_autostart.bin on each node. If this is not desired  (for
		  example,  on	diskless  nodes), a custom module handling au-
		  tostart information storage and retrieval can	be provided by
		  specifying environment variable ttb_autostart_module for the
		  application Runtime_Tools. The module	must  respond  to  the
		  following API:

		  write_config(Data) -_	ok:
		    Stores  the	provided data for further retrieval. It	is im-
		    portant to realize that the	data storage used must not  be
		    affected by	the node crash.

		  read_config()	-_ {ok,	Data} |	{error,	Error}:
		    Retrieves configuration stored with	write_config(Data).

		  delete_config() -_ ok:
		    Deletes  configuration stored with write_config(Data). No-
		    tice  that	after  this  call  any	subsequent  calls   to
		    read_config	must return {error, Error}.

		  resume implies the default FetchTimeout, which is 10 seconds

       p(Item,Flags) ->	Return


		 Return	= {ok,[{Item,MatchDesc}]}
		 Items = Item |	[Item]
		 Item  =  pid()	 | port() | RegName | {global,GlobalRegName} |
		 all | processes | ports | existing | existing_processes | ex-
		 isting_ports |	new | new_processes | new_ports
		 RegName = atom()
		 GlobalRegName = term()
		 Flags = Flag |	[Flag]

	      Sets  the	 specified  trace  flags on the	specified processes or
	      ports. Flag timestamp is always turned on.

	      See the Reference	Manual for module dbg for the  possible	 trace
	      flags. Parameter MatchDesc is the	same as	returned from dbg:p/2.

	      Processes	 can be	specified as registered	names, globally	regis-
	      tered names, or process identifiers. Ports can be	 specified  as
	      registered  names	 or  port identifiers. If a registered name is
	      specified, the flags are set on processes/ports with  this  name
	      on all active nodes.

	      Issuing  this  command starts the	timer for this trace if	option
	      timer is specified with tracer/2.

       tp, tpl,	ctp, ctpl, ctpg
       tpe, ctpe

	      These functions are to be	used with trace	flag call,  send,  and
	      'receive'	for setting and	clearing trace patterns.

	      When  trace  flag	 call  is set on a process, function calls are
	      traced on	that process if	a trace	pattern	is set for the	called

	      The send and 'receive' flags enable tracing of all messages sent
	      and received by the process/port.	Trace patterns	set  with  tpe
	      may  limit  traced  messages  based  on the message content, the
	      sender, and/or the receiver.

	      Trace patterns specify how to trace a function or	a  message  by
	      using  match  specifications. Match specifications are described
	      in the ERTS User's Guide.

	      These functions are equivalent to	the corresponding functions in
	      module dbg, but all calls	are stored in the history. The history
	      buffer makes it easy to create  configuration  files;  the  same
	      trace environment	can be set up many times, for example, to com-
	      pare two test runs. It also reduces the amount  of  typing  when
	      using ttb	from the Erlang	shell.

		  Sets trace patterns on global	function calls.

		  Sets trace patterns on local and global function calls.

		  Sets trace patterns on messages.

		  Clears trace patterns	on local and global function calls.

		  Clears trace patterns	on local function calls.

		  Clears trace patterns	on global function calls.

		  Clears trace patterns	on messages.

	      With tp and tpl, one of the match	specification shortcuts	can be
	      used (for	example, ttb:tp(foo_module, caller)).

	      The shortcuts are	as follows:

		* return - for [{'_',[],[{return_trace}]}] (report the	return
		  value	from a traced function)

		* caller  -  for  [{'_',[],[{message,{caller}}]}]  (report the
		  calling function)

		* {codestr,  Str}  -  for  dbg:fun2ms/1	 arguments  passed  as
		  strings (example: "fun(_) -_ return_trace() end")

       list_history() -> History


		 History = [{N,Func,Args}]

	      All calls	to ttb is stored in the	history. This function returns
	      the current content of the history. Any entry can	be  reexecuted
	      with  run_history/1  or  stored  in  a  configuration  file with

       run_history(N) -> ok | {error, Reason}


		 N = integer() | [integer()]

	      Executes the specified entry or entries from the	history	 list.
	      To list history, use list_history/0.


	      Equivalent to write_config(ConfigFile,Config,[]).

       write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}


		 ConfigFile = string()
		 Config	= all |	[integer()] | [{Mod,Func,Args}]
		 Mod = atom()
		 Func =	atom()
		 Args =	[term()]
		 Opts =	Opt | [Opt]
		 Opt = append

	      Creates  or  extends a configuration file, which can be used for
	      restoring	a specific configuration later.

	      The contents of the configuration	file  can  either  be  fetched
	      from   the   history   or	  specified  directly  as  a  list  of

	      If the complete history is to be	stored	in  the	 configuration
	      file,  Config  must be all. If only a selected number of entries
	      from the history are to be stored, Config	must be	a list of  in-
	      tegers pointing out the entries to be stored.

	      If  Opts	is not specified or if it is [], ConfigFile is deleted
	      and a new	file is	created. If Opts = [append], ConfigFile	is not
	      deleted. The new information is appended at the end of the file.

       run_config(ConfigFile) -> ok | {error,Reason}


		 ConfigFile = string()

	      Executes all entries in the specified configuration file.	Notice
	      that the history of the last trace is always available  in  file

       run_config(ConfigFile,NumList) -> ok | {error,Reason}


		 ConfigFile = string()
		 NumList = [integer()]

	      Executes selected	entries	from the specified configuration file.
	      NumList is a list	of integers pointing out the entries to	be ex-

	      To list the contents of a	configuration file, use	list_config/1.

	      Notice that the history of the last trace	is always available in
	      file ttb_last_config.

       list_config(ConfigFile) -> Config | {error,Reason}


		 ConfigFile = string()
		 Config	= [{N,Func,Args}]

	      Lists all	entries	in the specified configuration file.

       write_trace_info(Key,Info) -> ok


		 Key = term()
		 Info =	Data | fun() ->	Data
		 Data =	term()

	      File .ti contains	{Key,ValueList}	 tuples.  This	function  adds
	      Data to the ValueList associated with Key. All information writ-
	      ten with this function is	included in the	 call  to  the	format

       seq_trigger_ms()	-> MatchSpec

	      Equivalent to seq_trigger_ms(all).

       seq_trigger_ms(Flags) ->	MatchSpec


		 MatchSpec = match_spec()
		 Flags = all | SeqTraceFlag | [SeqTraceFlag]
		 SeqTraceFlag =	atom()

	      A	 match	specification  can  turn on or off sequential tracing.
	      This function returns a match specification, which turns on  se-
	      quential tracing with the	specified Flags.

	      This  match  specification can be	specified as the last argument
	      to tp or tpl. The	activated Item then becomes a trigger for  se-
	      quential	tracing.  This	means  that if the item	is called on a
	      process with trace flag call set,	the process is	"contaminated"
	      with token seq_trace.

	      If Flags = all, all possible flags are set.

	      The possible values for SeqTraceFlag are available in seq_trace.

	      For  a description of the	match_spec() syntax, see section Match
	      Specifications in	Erlang in ERTS,	 which	explains  the  general
	      match specification "language".

	      The system tracer	for sequential tracing is automatically	initi-
	      ated by ttb when a trace port is started with ttb:tracer/0,1,2.

	      An example of how	to use function	seq_trigger_ms/0,1 follows:

	      (tiger@durin)5> ttb:tracer().
	      (tiger@durin)6> ttb:p(all,call).
	      (tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).

	      Whenever mod:func(...) is	called after this, token seq_trace  is
	      set on the executing process.


	      Equivalent to stop([]).

       stop(Opts) -> stopped | {stopped, Dir}


		 Opts =	Opt | [Opt]
		 Opt  =	 nofetch  |  {fetch_dir, Dir} |	format | {format, For-
		 matOpts} | return_fetch_dir
		 Dir = string()
		 FormatOpts = see format/2

	      Stops tracing on all nodes. Logs and trace information files are
	      sent  to	the trace control node and stored in a directory named
	      ttb_upload_FileName-Timestamp, where Filename is	the  one  pro-
	      vided  with  {file, File}	during trace setup and Timestamp is of
	      the form yyyymmdd-hhmmss.	Even logs from nodes on	the  same  ma-
	      chine as the trace control node are moved	to this	directory. The
	      history list is saved to a file named ttb_last_config  for  fur-
	      ther  reference  (as  it is no longer accessible through history
	      and  configuration  management  functions,  like	 ttb:list_his-


		  Indicates  that  trace  logs	are  not to be collected after
		  tracing is stopped.

		{fetch,	Dir}:
		  Allows specification of the directory	to fetch the data  to.
		  If the directory already exists, an error is thrown.

		  Indicates  the  trace	 logs to be formatted after tracing is
		  stopped. All logs in the fetch directory are merged.

		  Indicates the	return value to	be {stopped, Dir} and not just
		  stopped. This	implies	fetch.


	      Returns  the  et	handler,  which	 can  be used with format/2 or

	      Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).


	      Equivalent to format(File,[]).

       format(File,Options) -> ok | {error, Reason}


		 File =	string() | [string()]
		   This	can be the name	of a binary log, a list	of such	 logs,
		   or  the  name  of a directory containing one	or more	binary
		 Options = Opt | [Opt]
		 Opt = {out,Out} | {handler,FormatHandler} | disable_sort
		 Out = standard_io | string()
		 FormatHandler = {Function, InitialState}
		 Function = fun(Fd,Trace,TraceInfo,State) -> State
		 Fd = standard_io | FileDescriptor
		   File	descriptor of the destination file Out.
		 Trace = tuple()
		   The trace message. For details, see	the  Reference	Manual
		   for module erlang.
		 TraceInfo = [{Key,ValueList}]
		   Includes  the  keys	flags, client, and node. If handler is
		   specified as	option to the tracer function,	this  is  also
		   included.  Also,  all  information  written	with  function
		   write_trace_info/2 is included.

	      Reads the	specified binary trace log(s). The logs	are  processed
	      in the order of their time stamps	as long	as option disable_sort
	      is not specified.

	      If FormatHandler = {Function,InitialState}, Function  is	called
	      for each trace message.

	      If FormatHandler = get_et_handler(), et_viewer in	application ET
	      is used for presenting the trace log graphically.	ttb provides a
	      few different filters that can be	selected from menu Filters and
	      scaling in the et_viewer.

	      If FormatHandler is not specified, a  default  handler  is  used
	      presenting each trace message as a text line.

	      The  state  returned from	each call of Function is passed	to the
	      next call, even if the next call is to format a message from an-
	      other log	file.

	      If  Out  is specified, FormatHandler gets	the file descriptor to
	      Out as the first parameter.

	      Out is ignored if	the et format handler is used.

	      Wrap logs	can be formatted one by	one or all at once. To	format
	      one  of  the wrap	logs in	a set, specify the exact file name. To
	      format the whole set of wrap logs, specify the name with	*  in-
	      stead of the wrap	count. For examples, see the User's Guide.

Ericsson AB			 observer 2.9				ttb(3)


Want to link to this manual page? Use this URL:

home | help