Provided by: erlang-manpages_22.0.7+dfsg-1build1_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, do not use module dbg in application Runtime_Tools 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 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

              Types:

                 Shortcut = shell | dbg

              Handy shortcuts for common tracing settings.

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

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

       tracer(Nodes) -> Result

              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}  |  {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.

              Options:

                Filename:
                  The specified Filename is 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.

                Client:
                  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.

                queue_size:
                  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 driver.

                process_info:
                  Indicates  if  process  information  is to be collected. If PI = true (which is
                  default),   each   process   identifier   Pid   is   replaced   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
                  functionality, set PI = false.

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

                shell:
                  Shortcut for {shell, true}.

                timer:
                  Indicates   that   the   trace  is  to  be  automatically  stopped  after  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
                  communication are always present. The timer starts after ttb:p/2 is issued,  so
                  you can set up your trace patterns before.

                overload_check:
                  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  initialize  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).

                flush:
                  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 Runtime_Tools remotely using rpc:call/4.

                  ttb  tries to fetch all logs from a reconnecting node before reinitializing the
                  trace. This must finish within FetchTimeout 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 autostart 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  important  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). Notice 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

              Types:

                 Return = {ok,[{Item,MatchDesc}]}
                 Items = Item | [Item]
                 Item = pid() | port() | RegName | {global,GlobalRegName} |  all  |  processes  |
                 ports  |  existing | existing_processes | existing_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  registered  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 function.

              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 compare two test runs. It also reduces the amount of typing when  using
              ttb from the Erlang shell.

                tp:
                  Sets trace patterns on global function calls.

                tpl:
                  Sets trace patterns on local and global function calls.

                tpe:
                  Sets trace patterns on messages.

                ctp:
                  Clears trace patterns on local and global function calls.

                ctpl:
                  Clears trace patterns on local function calls.

                ctpg:
                  Clears trace patterns on global function calls.

                ctpe:
                  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

              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 reexecuted with run_history/1 or stored in
              a configuration file with write_config/2,3.

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

              Types:

                 N = integer() | [integer()]

              Executes the specified entry or entries from the history list. To list history, use
              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

              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 {Mod,Func,Args}.

              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 integers 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}

              Types:

                 ConfigFile = string()

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

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

              Types:

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

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

              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}

              Types:

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

              Lists all entries in the specified configuration file.

       write_trace_info(Key,Info) -> ok

              Types:

                 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 written with this function is 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 specified Flags.

              This  match  specification  can be specified as the last argument to tp or tpl. The
              activated Item then becomes a trigger for sequential 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".

          Note:
              The  system  tracer for sequential tracing is automatically initiated 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().
              {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,  token  seq_trace  is  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  is  no longer accessible through
              history and configuration management functions, like ttb:list_history/0).

              Options:

                nofetch:
                  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.

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

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

       get_et_handler()

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

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

       format(File)

              Equivalent to 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
                   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 another 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  * instead of the wrap count. For examples, see the User's
              Guide.