Unix/Linux Go Back    


Linux 2.6 - man page for ttb (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ttb(3erl)			     Erlang Module Definition				ttb(3erl)

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

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

       When using ttb , dbg shall not be used in parallel.

EXPORTS
       tracer() -> Result

	      This is equivalent to tracer(node()) .

       tracer(Nodes) -> Result

	      This is equivalent to tracer(Nodes,[]) .

       tracer(Nodes,Opts) -> Result

	      Types  Result = {ok, ActivatedNodes} | {error,Reason}
		     Nodes = atom() | [atom()] | all | existing | new
		     Opts = [Opt]
		     Opt = {file,Client} | {handler, FormatHandler} | {process_info,PI}
		     Client = File | {local, File}
		     File = Filename | Wrap
		     Filename = string()
		     Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}
		     FormatHandler = See format/2
		     PI = true | false

	      This  function starts a file trace port on all given nodes and also points the sys-
	      tem tracer for sequential tracing to the same port.

	      The given Filename will be prefixed with the node name. Default Filename is "ttb".

	      File={wrap,Filename,Size,Count} 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 external "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.

	      The process_info option indicates if process information should be collected. If PI
	      = true (which is default), each process identifier  Pid  is  replaced  by  a  tuple
	      {Pid,ProcessInfo,Node}  ,  where	ProcessInfo  is  the process' registered name its
	      globally registered name, or its initial function. It is possible to turn off  this
	      functionality by setting PI = false .

       p(Procs,Flags) -> Return

	      Types  Return = {ok,[{Procs,MatchDesc}]}
		     Procs = Process | [Process] | all | new | existing
		     Process = pid() | atom() | {global,atom()}
		     Flags = Flag | [Flag]

	      This function sets the given trace flags on the given processes.

	      Please  turn  to the Reference manual for module dbg for details about the possible
	      trace flags. The parameter MatchDesc is the same as returned from dbg:p/2

	      Processes can be given as registered names, globally registered  names  or  process
	      identifiers.  If	a  registered  name is given, the flags are set on processes with
	      this name on all active nodes.

       tp, tpl, ctp, ctpl, ctpg

	      These functions should be used in combination with the call trace flag for  setting
	      and clearing trace patterns. When the call trace flag is set on a process, function
	      calls will be traced on that process if a trace pattern has been set for the called
	      function.  Trace patterns specifies how to trace a function by using match specifi-
	      cations. Match specifications are described in the User's Guide for the erlang run-
	      time system erts .

	      These  functions	are  equivalent  to  the corresponding functions in dbg , but all
	      calls are stored in the history. The history buffer makes it easy to create  config
	      files  so  that  the same trace environment can be setup several times, e.g. if you
	      want to compare two test runs. It also reduces the amount of typing when using  ttb
	      from the erlang shell.

		tp :
		  Set trace pattern on global function calls

		tpl :
		  Set trace pattern on local and global function calls

		ctp :
		  Clear trace pattern on local and global function calls

		ctpl :
		  Clear trace pattern on local function calls

		ctpg :
		  Clear trace pattern on global function calls

       list_history() -> History

	      Types  History = [{N,Func,Args}]

	      All  calls  to ttb is stored in the history. This function returns the current con-
	      tent of the history. Any entry can be re-executed with run_history/1 or stored in a
	      config file with write_config/2/3 .

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

	      Types  N = integer() | [integer()]

	      Executes	the  given  entry or entries from the history list. History can be listed
	      with list_history/0 .

       write_config(ConfigFile,Config)

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

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

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

	      This function creates or extends a config file which can be used	for  restoring	a
	      specific configuration later.

	      The  content  of	the  config  file can either be fetched from the history or given
	      directly as a list of {Mod,Func,Args} .

	      If the complete history is to be stored in the config file Config should be  all	.
	      If  only	a  selected  number  of entries from the history should be stored, Config
	      should be a list of integers pointing out the entries to be stored.

	      If Opt is not given or if it is [] , ConfigFile is deleted and a new file  is  cre-
	      ated.  If Opt = [append] , ConfigFile will not be deleted. The new information will
	      be appended at the end of the file.

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

	      Types  ConfigFile = string()

	      Executes all entries in the given config file.

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

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

	      Executes selected entries from the given config file. NumList is a list of integers
	      pointing out the entries to be executed.

	      The content of a config file can be listed with list_config/1 .

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

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

	      Lists all entries in the given config file.

       write_trace_info(Key,Info) -> ok

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

	      The  .ti	file contains {Key,ValueList} tuples. This function adds Data to the Val-
	      ueList associated with Key . All information written with  this  function  will  be
	      included in the call to the format handler.

       seq_trigger_ms() -> MatchSpec

	      Equivalent to seq_trigger_ms(all)

       seq_trigger_ms(Flags) -> MatchSpec

	      Types  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 sequential tracing with the given Flags .

	      This match specification can be given as the last argument to tp or tpl . The acti-
	      vated  Item  will  then become a trigger for sequential tracing. This means that if
	      the item is called on a process with the call trace flag set, the process  will  be
	      "contaminated" with the seq_trace token.

	      If Flags = all , all possible flags are set.

	      Please turn to the reference manual for the seq_trace module in the kernel applica-
	      tion to see the possible values  for  SeqTraceFlag  .  For  a  description  of  the
	      match_spec()  syntax, please turn to the User's guide for the runtime system ( erts
	      ). The chapter Match Specification in Erlang explains the general match  specifica-
	      tion "language".

   Note:
       The  system  tracer  for sequential tracing is automatically initiated by ttb when a trace
       port is started with ttb:tracer/0/1/2 .

       Example of how to use the seq_trigger_ms/0/1 function:

       (tiger@durin)5> ttb:tracer().
       {ok,[tiger@durin]}
       (tiger@durin)6> ttb:p(all,call).
       {ok,{[all],[call]}}
       (tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
       {ok,[{matched,1},{saved,1}]}
       (tiger@durin)8>

       Whenever mod:func(...) is called after this, the seq_trace token will be set on	the  exe-
       cuting process.

       stop()

	      Equivalent to stop([]) .

       stop(Opts) -> stopped

	      Types  Opts = [Opt]
		     Opt = fetch | format

	      Stops tracing on all nodes.

	      The  fetch option indicates that trace logs shall be collected from all nodes after
	      tracing is stopped. This option is useful if nodes on remote machines  are  traced.
	      Logs and trace information files are then sent to the trace control node and stored
	      in a directory named ttb_upload-Timestamp , where Timestamp is on the  form  yyyym-
	      mdd-hhmmss . Even logs from nodes on the same machine as the trace control node are
	      moved to this directory.

	      The format option indicates that the trace logs shall be formatted after tracing is
	      stopped.	Note  that  this option also implies the fetch option, i.e. logs are col-
	      lected in a new directory on the trace control node before formatting. All logs  in
	      the directory will be merged.

       format(File)

	      Same as format(File,[]) .

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

	      Types  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 logs.
		     Options = [Opt]
		     Opt = {out,Out} | {handler,FormatHandler}
		     Out = standard_io | string()
		     FormatHandler = {Function, InitialState} | et
		     Function = fun(Fd,Trace,TraceInfo,State) -> State
		     Fd = standard_io | FileDescriptor
		     This is the file descriptor of the destination file Out
		     Trace = tuple()
		     This is the trace message. Please turn  to  the  Reference  manual  for  the
		     erlang module for details.
		     TraceInfo = [{Key,ValueList}]
		     This  includes the keys flags , client and node , and if handler is given as
		     option to the tracer function, this is also included. In addition all infor-
		     mation written with the write_trace_info/2 function is included.

	      Reads  the given binary trace log(s). If a directory or a list of logs is given and
	      the timestamp flag was set during tracing, the trace messages  from  the	different
	      logs are merged according to the timestamps.

	      If FormatHandler = {Function,InitialState} , Function will be called for each trace
	      message. If FormatHandler = et , et_viewer in the Event Tracer application (  et	)
	      is used for presenting the trace log graphically. ttb provides a few different fil-
	      ters which can be selected from the Filter menu in the et_viewer . If FormatHandler
	      is not given, a default handler is used which presents each trace message as a line
	      of text.

	      If Out is given, FormatHandler gets the filedescriptor to Out as the first  parame-
	      ter.

	      Out is ignored if FormatHandler = et .

	      Wrap  logs  can be formatted one by one or all in one go. To format one of the wrap
	      logs in a set, give the exact name of the file. To format the  whole  set  of  wrap
	      logs,  give  the	name  with '*' instead of the wrap count. See examples in the ttb
	      User's Guide.

Ericsson AB				  observer 0.9.9				ttb(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:39 PM.