From e6b2edc8027c40db4c12f8f081648cda4634f9f7 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Mon, 23 Nov 2015 18:27:25 +0100 Subject: Observer: Editorial changes in documentation --- lib/observer/doc/src/ttb.xml | 515 +++++++++++++++++++++++-------------------- 1 file changed, 281 insertions(+), 234 deletions(-) (limited to 'lib/observer/doc/src/ttb.xml') diff --git a/lib/observer/doc/src/ttb.xml b/lib/observer/doc/src/ttb.xml index 0a50a20716..2b637551db 100644 --- a/lib/observer/doc/src/ttb.xml +++ b/lib/observer/doc/src/ttb.xml @@ -4,8 +4,7 @@
- 2002 - 2013 + 20022016 Ericsson AB, All Rights Reserved @@ -25,27 +24,28 @@ ttb - Siri hansen, Bartlomiej Puzon + Siri Hansen, Bartlomiej Puzon 1 2010-08-13 PA1 - ttb.sgml + ttb.xml
ttb A base for building trace tools for distributed systems. -

The Trace Tool Builder ttb is a base for building trace +

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.

+

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

 start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result - Start a trace port on each given node. + Start a trace port on each specified node. Result = see p/2 Nodes = see tracer/2 @@ -57,48 +57,56 @@

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}}]) -

is equivalent to

-ttb:start_trace([Node, OtherNode], [{file, File}, {handler,{fun myhandler/4, S}}]), + 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)
+ttb:p(all, call).
 + tracer() -> Result - This is equivalent to tracer(node()). + Equivalent to tracer(node()). -

This is equivalent to tracer(node()).

+

Equivalent to tracer(node()).

 + tracer(Shortcut) -> Result - Handy shortcuts for common tracing settings + Handy shortcuts for common tracing settings. 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 - This is equivalent to tracer(Nodes,[]). + Equivalent to tracer(Nodes,[]). -

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

+

Equivalent to tracer(Nodes,[]).

 + tracer(Nodes,Opts) -> Result - Start a trace port on each given node. + Start a trace port on each specified node. Result = {ok, ActivatedNodes} | {error,Reason} Nodes = atom() | [atom()] | all | existing | new @@ -120,98 +128,109 @@ ttb:p(all, call) 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 +

Starts a file trace port on all specified nodes + and 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 +

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

-

The process_info option indicates if process - information should be collected. If PI = true (which is + it is written to file.

 + 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 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 + 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 ttb:stop/2 command if specified (default is []). - Note that the timing is approximate, as delays related to + 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. -

-

The overload_check option allows to enable overload + 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 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 + 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 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 + 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 - (i.e. on diskless nodes), a custom module to handle autostart + (for example, on diskless nodes), a custom module handling 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:

- + environment variable ttb_autostart_module for the application + Runtime_Tools. The module must respond to the following API:

+ write_config(Data) -> ok - Store the provided data for further retrieval. It is +

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. + be affected by the node crash.

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

Retrieves 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}. +

Deletes configuration stored with write_config(Data). + Notice that after this call any subsequent calls to read_config + must return {error, Error}.

 - -

The resume option implies the default FetchTimeout, which is + +

resume implies the default FetchTimeout, which is 10 seconds

+ + + + p(Procs,Flags) -> Return - Sets the given trace flags on the given processes. + Set the specified trace flags on the specified processes. Return = {ok,[{Procs,MatchDesc}]} Procs = Process | [Process] | all | new | existing @@ -219,95 +238,101 @@ ttb:p(all, call) Flags = Flag | [Flag] -

This function sets the given trace flags on the given - processes. The timestamp flag is always turned on. +

Sets the specified trace flags on the specified + processes. Flag timestamp 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 +

See the Reference Manual for module + dbg + and 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. If a registered name + is specified, 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. +

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

+ tp, tpl, ctp, ctpl, ctpg Set and clear trace patterns. -

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 +

These functions are to be used with + trace flag call 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. Trace patterns + specify how to trace a function by using match specifications. Match specifications are described in the - User's Guide for the erlang runtime system erts. + ERTS User's Guide.

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 + 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. + Erlang shell.

tp - Set trace pattern on global function calls +

Sets trace patterns on global function calls.

 tpl - Set trace pattern on local and global function calls +

Sets trace patterns on local and global function calls.

 ctp - Clear trace pattern on local and global function - calls +

Clears trace patterns on local and global function + calls.

 ctpl - Clear trace pattern on local function calls +

Clears trace patterns on local function calls.

 ctpg - Clear trace pattern on global function calls +

Clears trace patterns 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:

- - +

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) - 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 - Returns all calls stored in history + Return all calls stored in 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 re-executed with run_history/1 or stored in a - config file with write_config/2/3.

+ can be reexecuted with run_history/1 or stored in a + configuration file with write_config/2,3.

 + run_history(N) -> ok | {error, Reason} - Executes one entry of the history + Execute one entry of the history. N = integer() | [integer()] -

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

+

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,[]). @@ -315,9 +340,10 @@ ttb:p(all, call)

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

 + write_config(ConfigFile,Config,Opts) -> ok | {error,Reason} - Creates a config file. + Create a configuration file. ConfigFile = string() Config = all | [integer()] | [{Mod,Func,Args}] @@ -328,92 +354,97 @@ ttb:p(all, call) Opt = append -

This function creates or extends a config file which can be +

Creates or extends a configuration 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 +

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 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 +

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 given or if it is [], +

If Opts is not specified 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.

+ Opts = [append], ConfigFile is not deleted. + The new information is appended at the end of the file.

 + run_config(ConfigFile) -> ok | {error,Reason} - Executes all entries in a config file. + Execute all entries in a configuration file. 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.

+

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} - Executes selected entries from a config file. + Execute selected entries from a configuration file. ConfigFile = string() NumList = [integer()] -

Executes selected entries from the given config +

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

-

The content of a config file can be listed with +

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

-

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

+

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

 + list_config(ConfigFile) -> Config | {error,Reason} - Lists all entries in a config file. + List all entries in a configuration file. ConfigFile = string() Config = [{N,Func,Args}] -

Lists all entries in the given config file.

+

Lists all entries in the specified configuration file.

 + write_trace_info(Key,Info) -> ok - Writes any information to the .tifile. + Write any information to file .ti. Key = term() Info = Data | fun() -> Data Data = term() -

The .ti file contains {Key,ValueList} - tuples. This function adds Data to the ValueList +

File .ti 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.

+ function is included in the call to the format handler.

 + seq_trigger_ms() -> MatchSpec - Equivalent to seq_trigger_ms(all) + Equivalent to seq_trigger_ms(all). -

Equivalent to seq_trigger_ms(all)

+

Equivalent to seq_trigger_ms(all).

 + seq_trigger_ms(Flags) -> MatchSpec - Returns a match_spec() which starts sequential tracing + Return a match_spec() which starts sequential tracing. MatchSpec = match_spec() Flags = all | SeqTraceFlag | [SeqTraceFlag] @@ -421,54 +452,55 @@ ttb:p(all, call)

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. + tracing. This function returns a match specification, which + turns on sequential tracing with the specified 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. +

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.

-

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". +

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 initiated by ttb when a trace port is - started with ttb:tracer/0/1/2.

+ started with ttb:tracer/0,1,2.

 -

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

- -(tiger@durin)5> ttb:tracer(). +

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).
+(tiger@durin)6> ttb:p(all,call).
 {ok,{[all],[call]}}
-(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
+(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.

+(tiger@durin)8>
+

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

 + stop() - Equivalent to stop([]) + Equivalent to stop([]).

Equivalent to stop([]).

 + stop(Opts) -> stopped | {stopped, Dir} - Stop tracing and fetch/format logs from all nodes + Stop tracing and fetch/format logs from all nodes. Opts = Opt | [Opt] Opt = nofetch | {fetch_dir, Dir} | format | {format, FormatOpts} | return_fetch_dir @@ -485,88 +517,103 @@ ttb:p(all, call) 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 + for further reference (as it is no 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 +

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

-

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

+ 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 et handler. + Return the 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()}]).

+

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) - Same as format(File,[]). + Equivalent to format(File,[]). -

Same as format(File,[]).

+

Equivalent to format(File,[]).

 + format(File,Options) -> ok | {error, Reason} - Format a binary trace log + Format a binary trace log. 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. + 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 + 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. + The trace message. For details, see the Reference Manual for + module erlang. 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. + 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 given binary trace log(s). The logs are processed - in the order of their timestamp as long as disable_sort - option is not given. +

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 will be called for each trace message. If - FormatHandler = get_et_handler(), et_viewer in - the Event Tracer application (et) is used for presenting + 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 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. + 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 next call is to format a message from another log file. +

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 given, FormatHandler gets the +

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

-

Out is ignored if et format handler is used. +

Out is ignored if the 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.

+

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

-- cgit v1.2.3