From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/observer/doc/src/ttb.xml | 416 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 lib/observer/doc/src/ttb.xml (limited to 'lib/observer/doc/src/ttb.xml') diff --git a/lib/observer/doc/src/ttb.xml b/lib/observer/doc/src/ttb.xml new file mode 100644 index 0000000000..fcaa1c2504 --- /dev/null +++ b/lib/observer/doc/src/ttb.xml @@ -0,0 +1,416 @@ + + + + +
+ + 2002 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + ttb + Siri hansen + + 1 + + + 2002-02-25 + PA1 + ttb.sgml +
+ 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, dbg shall not be used in parallel.

+ + + + tracer() -> Result + This is equivalent to tracer(node()). + +

This is equivalent to tracer(node()).

+ + + + tracer(Nodes) -> Result + This is equivalent to tracer(Nodes,[]). + +

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

+ + + + tracer(Nodes,Opts) -> Result + Start a trace port on each given node. + + 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 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. +

+ + + + p(Procs,Flags) -> Return + Sets the given trace flags on the given processes. + + 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 + 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 + 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 + + + + + list_history() -> History + Returns 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.

+ + + + run_history(N) -> ok | {error, Reason} + Executes 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.

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

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

+ + + + write_config(ConfigFile,Config,Opt) -> ok | {error,Reason} + Creates a config file. + + 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 created. 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} + Executes all entries in a config file. + + ConfigFile = string() + + +

Executes all entries in the given config file.

+ + + + run_config(ConfigFile,NumList) -> ok | {error,Reason} + Executes selected entries from a config file. + + 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} + Lists all entries in a config file. + + ConfigFile = string() + Config = [{N,Func,Args}] + + +

Lists all entries in the given config file.

+ + + + write_trace_info(Key,Info) -> ok + Writes any information to the .tifile. + + 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) + +

Equivalent to seq_trigger_ms(all)

+ + + + seq_trigger_ms(Flags) -> MatchSpec + Returns a match_spec() which starts sequential tracing + + 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". +

+ +

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([]) + +

Equivalent to stop([]).

+ + + + stop(Opts) -> stopped + Stop tracing and fetch/format logs from all nodes + + 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 yyyymmdd-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 + collected 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,[]). + +

Same as format(File,[]).

+ + + + format(File,Options) -> ok | {error, Reason} + 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. + 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 erlangmodule for details. + TraceInfo = [{Key,ValueList}] + This includes the keys flags, clientand node, and if handleris 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). 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 + 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. +

+

If Out is given, FormatHandler gets the + filedescriptor to Out as the first parameter. +

+

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.

+ + + + + -- cgit v1.2.3