Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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

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

              Types:

                 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 list which is in turn passed to ttb:tpl. The call:

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

              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

              This is equivalent to tracer(node()).

       tracer(Shortcut) -> Result

              Types:

                 Shortcut = shell | dbg

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

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

       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]
                 Opt = {file,Client} | {handler, FormatHandler} |  {process_info,PI}  |  shell  |
                 {shell,  ShellSpec}  |  {timer,  TimerSpec}  |  {overload_check,  {MSec, Module,
                 Function}} | {flush, MSec} | resume | {resume, FetchTimeout}
                 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

              This function starts a file trace port on all  given  nodes  and  also  points  the
              system 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.

              The {shell, ShellSpec} option indicates that the trace messages should  be  printed
              on  the  console  as they are received by the tracing process. This implies {local,
              File} trace client. If the ShellSpec is only (instead of true), no trace  logs  are
              stored.

              The shell option is a shortcut for {shell, true}.

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

              The  overload_check  option  allows  to enable overload checking on the nodes under
              trace. Module:Function(check) is performed each MSec  milliseconds.  If  the  check
              returns true, the tracing is disabled on a given node.
              Module:Function  should  be  able  to  handle at least three atoms: init, check and
              stop. init and stop give the user a possibility to  initialize  and  clean  up  the
              check environment.
              When a node gets overloaded, it is not possible to issue ttb:p nor any command from
              the ttb:tp family, as it would lead to inconsistent tracing state (different  trace
              specifications on different node).

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

              {resume,  FetchTimeout}  enables  the  autoresume feature. Whenever enabled, remote
              nodes try to reconnect to the controlling node in case  they  were  restarted.  The
              feature  requires  runtime_tools application 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 may be performed manually by starting runtime_tools remotely using
              rpc:call/4.
              ttb tries to fetch all logs from a  reconnecting  node  before  reinitializing  the
              trace. This has to finish within FetchTimeout milliseconds or is aborted
              By  default,  autostart information is stored in a file called ttb_autostart.bin on
              each node. If this is not desired (i.e. on diskless  nodes),  a  custom  module  to
              handle  autostart  information  storage and retrieval can be provided by specifying
              ttb_autostart_module environment variable for the  runtime_tools  application.  The
              module has to respond to the following API:

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

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

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

              The resume option implies the default FetchTimeout, which is 10 seconds

       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. The timestamp flag
              is always turned on.

              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.

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

       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
              specifications. Match specifications are described in  the  User's  Guide  for  the
              erlang runtime 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

              With  tp  and  tpl  one  of  match  specification  shortcuts  may be used (example:
              ttb:tp(foo_module, caller)). The shortcuts are:

       list_history() -> History

              Types:

                 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 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,Opts) -> ok | {error,Reason}

              Types:

                 ConfigFile = string()
                 Config = all | [integer()] | [{Mod,Func,Args}]
                 Mod = atom()
                 Func = atom()
                 Args = [term()]
                 Opts = Opt | [Opt]
                 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  Opts  is  not  given  or  if  it is [], ConfigFile is deleted and a new file is
              created. If Opts = [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. Note that the history of the last
              trace is always available in the file named ttb_last_config.

       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.

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

       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
              ValueList  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
              activated 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
              application  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 specification
              "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
              executing process.

       stop()

              Equivalent to stop([]).

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

              Types:

                 Opts = Opt | [Opt]
                 Opt  =  nofetch  |  {fetch_dir,  Dir}  |  format  |   {format,   FormatOpts}   |
                 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 provided with {file, File} during trace setup and Timestamp is
              of the form yyyymmdd-hhmmss. Even logs from nodes on the same machine as the  trace
              control node are moved to this directory. The history list is saved to a file named
              ttb_last_config for further reference (as it will be not longer accessible  through
              history and configuration management functions (like ttb:list_history/0).

              The  nofetch  option indicates that trace logs shall not be collected after tracing
              is stopped.

              The {fetch, Dir} option allows to specify the directory to fetch the  data  to.  If
              the directory already exists, an error is thrown.

              The format option indicates that the trace logs shall be formatted after tracing is
              stopped. All logs in the fetch directory will  be  merged.  You  may  use  {format,
              FormatOpts} to pass additional arguments to format/2.

              The  return_fetch_dir  option  indicates  that the return value should be {stopped,
              Dir} and not just stopped. This implies fetch.

       get_et_handler()

              The et handler returned by the function may be  used  with  format/2  or  tracer/2.
              Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).

       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]
                 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
                   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
                   erlangmodule 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
                   information written with the write_trace_info/2function is included.

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

              If FormatHandler = {Function,InitialState}, Function will be called for each  trace
              message.  If  FormatHandler  =  get_et_handler(),  et_viewer  in  the  Event Tracer
              application (et) is used for presenting the trace log graphically. ttb  provides  a
              few  different filters 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.

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

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

              Out is ignored if et format handler is used.

              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.