/erlang_otp/_sources/lib/inviso-0.6/doc/html/inviso.txt
Plain Text | 1034 lines | 738 code | 296 blank | 0 comment | 0 complexity | 6a8993d9db1e01c73bc919fa7d1b223d MD5 | raw file
- ======================================
- Lib - Inviso-0.6 - Doc - Html - Inviso
- ======================================
- ` <http://www.ericsson.com/technology/opensource/erlang>`__
- inviso
- ======
- MODULE
- ~~~~~~
- inviso
- MODULE SUMMARY
- ~~~~~~~~~~~~~~
- Main API Module to the Inviso Tracer
- DESCRIPTION
- ~~~~~~~~~~~
- With the inviso API runtime components can be started and tracing
- managed across a network of distributed Erlang nodes, using a control
- component also started with inviso API functions.
- Inviso can be used both in a distributed environment and in a non-
- distributed. API functions not taking a list of nodes as argument
- works on all started runtime components. If it is the non-distributed
- case, that is the local runtime component. The API functions taking a
- list of nodes as argument, or as part of one of the arguments, can not
- be used in a non-distributed environment. Return values named
- NodeResult refers to return values from a single Erlang node, and will
- therefore be the return in the non-distributed environment.
- EXPORTS
- ~~~~~~~
- start() -> {ok,pid()} | {error,Reason}
- start(Options) -> {ok,pid()} | {error,Reason}
- Types:
- Options = [Option]
- Options may contain both options which will be default options to a
- runtime component when started, and options to the control component.
- See add_nodes/3 for details on runtime component options. The control
- component recognizes the following options:
- :{subscribe,Pid}: Making the process Pid receive Inviso events from
- the control component. Starts a control component process on the local
- node. A control component must be started before runtime components
- can be started manually or otherwise accessed through the inviso API.
- stop() -> shutdown
- Stops the control component. Runtime components are left as is. They
- will behave according to their dependency values.
- add_node(RTtag) -> NodeResult | {error,Reason}
- add_node(RTtag,Options) -> NodeResult | {error,Reason}
- Types:
- RTtag = PreviousRTtag = term()
- Options = [Option]
- Option -- see below
- Option = {dependency,Dep}
- Dep = int() | infinity
- The timeout, in milliseconds, before the runtime component will
- terminate if abandoned by this control component. Option =
- {overload,Overload} | overload
- Controls how and how often overload checks shall be performed. Just
- overloadspecifies that no loadcheck shall be performed. Overload =
- Interval | {LoadMF,Interval,InitMFA,RemoveMFA}
- LoadMF = {Mod,Func} | function()/1
- Interval = int() | infinity
- Interval is the time in milliseconds between overload checks.
- InitMFA = RemoveMFA = {Mod,Func,ArgList} | void
- When starting up the runtime component or when changing options (see
- change_options/2) the overload mechanism is initialized with a call to
- the InitMFAfunction. It shall return LoadCheckData. Every time a load
- check is performed, LoadMFis called with LoadCheckDataas its only
- argument. LoadMFshall return okor {suspend,Reason}. When the runtime
- component is stopped or made to change options involving changing
- overload-check, the RemoveMFAfunction is called. Its return value is
- discarded. NodeResult = {ok,NAns} | {error,Reason}
- NAns = new | {adopted,State,Status,PreviousRTtag} | already_added
- State = new | tracing | idle
- Status = running | {suspended,SReason}
- Starts or tries to connect to an existing runtime component at the
- local node, regardless if the system is distributed or not. Options
- will override any default options specified at start-up of the control
- component.
- The PreviousRTtag can indicate if the incarnation of the runtime
- component at the node in question was started by "us" and then can be
- expected to do tracing according to "our" instructions or not.
- add_node_if_ref(RTtag) -> NodeResult |
- {error,{wrong_reference,OtherTag}} | {error,Reason}
- add_node_if_ref(RTtag,Options) -> NodeResult |
- {error,{wrong_reference,OtherRef}} | {error,Reason}
- Types:
- OtherRef = term()
- rttag of the running incarnation
- As add_node/1,2 but will only adopt the runtime component if its rttag
- is RTtag.
- add_nodes(Nodes,RTtag) -> {ok,NodeResults} | {error,Reason}
- add_nodes(Nodes,RTtag,Options) -> {ok,NodeResults} | {error,Reason}
- Types:
- Nodes = [Node]
- NodeResults = [{Node,NodeResult}]
- As add_node/1,2 but for a distributed environment.
- add_nodes_if_ref(Nodes,RTtag) -> NodeResult | {error,Reason}
- add_nodes_if_ref(Nodes,RTtag,Options) -> NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- NodeResults = [{Node,NodeResult}]
- As add_node_if_ref/1,2 but for a distributed environment.
- stop_nodes() -> {ok,NodeResults} | NodeResult
- stop_nodes(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Stops runtime component on Nodes. stop_nodes/0 will if the control
- component is running on a distributed node stop all runtime
- components. And if running on a non distributed node, stop the local
- and only runtime component.
- stop_all() = {ok,NodeResults} | NodeResult
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- A combination of stop/0 and stop_nodes/0.
- change_options(Options) -> NodeResult | {ok,NodeResults} |
- {error,Reason}
- change_options(Nodes,Options) -> {ok,NodeResults} | {error,Reason}
- Types:
- Nodes = [Node]
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Changes the options for one or several runtime components. If for
- instance overload is redefined, the previous overload will be stopped
- and the new started. See add_node/1 for details on Options.
- init_tracing(TracerData) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- init_tracing(TracerList) -> {ok,NodeResults} | {error,Reason}
- init_tracing(Nodes,TracerData) -> {ok,NodeResults} | {error,Reason}
- Types:
- TracerData = [{trace,LogTD} [,{ti,TiTD}] }] | LogTD
- LogTD = {HandlerFun,Data1} | collector | {relayer,CollectingNode} |
- {ip,IPPortParameters} | {file,FilePortParameters}
- TiTD = {file,FileName} | {file,FileName,TiSpec} | {relay,Node}
- TiSpec = {InitMFA,RemoveMF,CleanMF}
- InitMFA = {Mi,Fi,Argsi}
- RemoveMF = {Mr,Fr} | void
- CleanMF = {Mc,Fc}
- Mi = Fi = Mr = Fr = Mc = Fd = atom()
- Argsi = [term()]
- TracerList = [{Node,TracerData}]
- IPPortParameters = Portno | {Portno,Qsize}
- Portno = tcp_portno()
- Qsize = int()
- FilePortParameters = {Filename,wrap,Tail,{time,WrapTime},WrapCnt} |
- {FileName,wrap,Tail,WrapSize,WrapCnt} | {FileName,wrap,Tail,WrapSize}
- | {FileName,wrap,Tail} | FileName
- FileName = string()
- Tail = string() =/= ""
- WrapTime = WrapCnt = WrapSize = int() >0
- TracerList = [{Node,TracerData}]
- Nodes = [Node]
- HandlerFun = function()/2;
- HandlerFun(TraceMsg,Data1) -> NewData
- CollectingNode = pid() | node()
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,LogResults} | {error,NReason}
- LogResults = [LogResult]
- LogResult = {trace_log,LogRes} | {ti_log,LogRes}
- LogRes = ok | {error,Reason}
- Starts the tracing at the specified nodes, meaning that the runtime
- components transits from the state new or idle to tracing. For trace
- messages to be generated, there must of course also be trace pattern
- and/or trace flags set. Such can not be set before tracing has been
- initiated with init_tracing/1,2.
- TracerData controls how the runtime component will handle generated
- trace messages. The trace tag controls how regular trace messages are
- handled. The ti tag controls if and how trace information will be
- stored and the meta tracer will be activated. That is if ti is
- omitted, no meta tracer will be started as part of the runtime
- component. It is possible to have ti without trace, but most likely
- not useful.
- The ip and file trace tracerdata instructions results in using the
- built in trace ip-port and file-port respectively. relayer will result
- in that all regular trace messages are forwarded to a runtime
- component at the specified node. Using a HandlerFun will result in
- that every incoming regular trace message is applied to the
- HandlerFun. collector can be used to use this runtime component to
- receive relayed trace messages and print them to the shell.
- The trace information can be configured to either write trace
- information to a plain trace information file or to relay it to
- another inviso meta tracer on another node. The inviso meta tracer is
- capable of matching function calls with their function returns (only
- if return_trace is activated in the meta trace match specification for
- the function in question). This is necessary since it may not be
- possible to decide what to do, if anything shall be done at all, until
- the return value of the function call is examined.
- To be able to match calls with returns a state can be saved when
- detecting a function call in a public loop data structure kept by the
- inviso meta tracer. The public loop data structure is given as
- argument to a handler-function called whenever a meta trace message
- arrives to the inviso meta tracer (both function calls and function
- returns). The public loop data structure is first initiated by the
- Mi:Fi function which takes the items in Argsi as arguments. Fi shall
- return the initial public loop data structure. When meta tracing is
- stopped, either because tracing is stopped or because tracing is
- suspended, the Mr:Fr(PublicLoopData) is called to offer a possibility
- to clean-up. Note that for every function meta-tracing is activated, a
- public loop data modification function can be speficied. That function
- will prepare the current loop data structure for this particular
- function.
- Further there is a risk that function call states becomes abandoned
- inside the public loop data structure. This will happen if a function
- call is entered into the public loop data structure, but no function
- return occurs. To prevent the public loop data structure from growing
- infinitely the clean function Fc will periodically be called with the
- public loop data structure as argument. Elements entered into the
- public loop data structure as a result of a function call must contain
- a timestamp for the Fc to be able to conclude if it is abandoned or
- not. Fc shall return a new public loop data structure.
- When initiating tracing involving trace information without a TiSpec,
- a default public loop data structure will be initiated to handle
- locally registered process aliases. The default public loop data
- structure is a two-tuple where the first element is used by the meta
- tracing on the BIF register/2. The second element is left for user
- usage.
- The default public loop data structure may be extended with more
- element positions. The first position must be left to the
- implementation of registered-name translations. If the public loop
- data structure is changed no longer meeting this requirement, the
- tpm_localnames/0,1 and tpm_globalnames/0,1 can no longer be used.
- A wrap files specification is used to limit the disk space consumed by
- the trace. The trace is written to a limited number of files each with
- a limited size. The actual filenames are Filename ++ SeqCnt ++ Tail,
- where SeqCnt counts as a decimal string from 0 to WrapCnt and then
- around again from 0. When a trace message written to the current file
- makes it longer than WrapSize, that file is closed, if the number of
- files in this wrap trace is as many as WrapCnt the oldest file is
- deleted then a new file is opened to become the current. Thus, when a
- wrap trace has been stopped, there are at most WrapCnt trace files
- saved with a size of at least WrapSize (but not much bigger), except
- for the last file that might even be empty. The default values are
- WrapSize == 128*1024 and WrapCnt == 8.
- The SeqCnt values in the filenames are all in the range 0 through
- WrapCnt with a gap in the circular sequence. The gap is needed to find
- the end of the trace.
- If the WrapSize is specified as {time,WrapTime}, the current file is
- closed when it has been open more than WrapTime milliseconds,
- regardless of it being empty or not.
- The ip trace driver has a queue of QSize messages waiting to be
- delivered. If the driver cannot deliver messages as fast as they are
- produced by the runtime system, they are dropped. The number of
- dropped messages are indicated in the trace log as separate trace
- message.
- stop_tracing(Nodes) -> {ok,NodeResults} | {error,Reason}
- stop_tracing() -> {ok,NodeResults} | NodeResult
- Types:
- Nodes = [Node]
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,State} | {error,Reason}
- State = new | idle
- Stops tracing on all or specified Nodes. Flushes the trace buffer if a
- trace-port is used, closes the trace-port and removes all trace flags
- and meta-patterns. The nodes are called in parallel.
- Stopping tracing means going to state idle<c>. If the runtime
- component was already in state <c>new, it will of course remain in
- state new (then there was no tracing to stop).
- clear() -> {ok,NodeResults} | NodeResult
- clear(Nodes,Options) -> {ok,NodeResults} | {error,Reason}
- clear(Options) -> {ok,NodeResults} | NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- Options = [Option]
- Option = keep_trace_patterns | keep_log_files
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,{new,Status}} | {error,Reason}
- Status = running | {suspended,SReason}
- Stops all tracing including removing meta-trace patterns. Removes all
- trace patterns. If the node is tracing or idle, trace-logs belonging
- to the current tracerdata are removed. Hence the node is returned to
- state new. Note that the node can still be suspended.
- Various options can make the node keep set trace patterns and log-
- files. The node still enters the new state.
- tp(Nodes,Mod,Func,Arity,MatchSpec,Opts) ->
- tp(Nodes,Mod,Func,Arity,MatchSpec) -> {ok,NodeResults} |
- {error,Reason}
- tp(Mod,Func,Arity,MatchSpec,Opts) ->
- tp(Mod,Func,Arity,MatchSpec) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- tp(Nodes,PatternList) -> {ok,NodeResults} | {error,Reason}
- tp(PatternList) -> {ok,NodeResults} | NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- Mod = Func = atom() | '_'
- Arity = int() | '_'
- MatchSpec = true | false | [] | matchspec()
- PatternList = [Pattern],
- Pattern = {Mod,Func,Arity,MatchSpec,Opts}
- Opts = [Opt]
- Opt = only_loaded
- NodeResults = [NodeResult]
- NodeResult = {ok,[Ans]} | {error,Reason}
- Ans = int() | {error,Reason}
- Set trace pattern (global) on specified or all nodes. The integer
- replied if the call was successfully describes the number of matched
- functions. The functions without a Nodes argument means all nodes, in
- a non-distributed environment it means the local node. Using wildcards
- follows the rules for wildcards of erlang:trace_pattern/3. It is for
- instance illegal to specify M == '_' while F is not '_'.
- When calling several nodes, the nodes are called in parallel.
- The option only_loaded will prevent modules not loaded (yet) into the
- runtime system to become loaded just as a result of that a trace
- pattern is requested to be set on it. Otherwise modules are
- automatically loaded if not already loaded (since the module must be
- present for a trace pattern to be set on it). The latter does not
- apply if the wildcard '_' is used as module specification.
- tpl(Nodes,Mod,Func,Arity,MatchSpec) ->
- tpl(Nodes,Mod,Func,Arity,MatchSpec,Opts) -> {ok,NodeResults} |
- {error,Reason}
- tpl(Mod,Func,Arity,MatchSpec) ->
- tpl(Mod,Func,Arity,MatchSpec,Opts) -> {ok,NodeResults} | NodeResult|
- {error,Reason}
- tpl(Nodes,PatternList) -> {ok,NodeResults} | {error,Reason}
- tpl(PatternList) -> {ok,NodeResults} | NodeResult | {error,Reason}
- See tp/N function above for details on arguments and return values.
- Set local trace pattern on specified functions. When calling several
- nodes, the nodes are called in parallel.
- ctp(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
- ctp(Mod,Func,Arity) -> {ok,NodeResults} | NodeResult | {error,Reason}
- See tp/N for argument descriptions.
- Clear global trace patterns. When calling several nodes, the nodes are
- called in parallel.
- ctpl(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
- ctpl(Mod,Funct,Arity) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- See tp/N for argument description.
- Clear local trace patterns. When calling several nodes, the nodes are
- called in parallel.
- tf(Nodes,PidSpec,FlagList) -> {ok,NodeResults} | {error,Reason}
- tf(PidSpec,FlagList) -> {ok,NodeResults} | NodeResult | {error,Reason}
- tf(Nodes,TraceConfList) -> {ok,NodeResults} | {error,Reason}
- tf(NodeTraceConfList) -> {ok,NodeResults} | {error,Reason}
- tf(TraceConfList) -> {ok,NodeResults} | NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- NodeTraceConfList = [{Node,TraceConfList}]
- TraceConfList = [{PidSpec,FlagList}]
- FlagList = [Flag]
- PidSpec = all | new| existing | pid() | locally_registered_name()
- Flag -- see erlang:trace/3
- NodeResult = {ok,[Ans]} | {error,Reason}
- Ans = int() | {error,Reason}
- Set process trace flags on processes on all or specified nodes. The
- integer returned if the call was successful describes the matched
- number of processes. The functions without a Nodes argument means all
- nodes, in a non-distributed environment it means the local node.
- There are many combinations which does not make much sense. For
- instance specifying a certain process identifier at all nodes. Or an
- empty TraceConfList for all nodes.
- When calling several nodes, the nodes are called in parallel.
- ctf(Nodes,PidSpec,FlagList) -> {ok,NodeResults} | {error,Reason}
- ctf(PidSpec,FlagList) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- ctf(Nodes,TraceConfList) -> {ok,NodeResults} | {error,Reason}
- ctf(TraceConfList) -> {ok,NodeResults} | NodeResult | {error,Reason}
- See tf/N for arguments and return value description.
- Clear process trace flags on all or specified nodes. When calling
- several nodes, the nodes are called in parallel.
- ctf_all(Nodes) -> {ok,NodeResults} | {error,Reason}
- ctf_all() -> {ok,NodeResults} | NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Clears all trace flags on all or specified nodes. Just for
- convenience.
- init_tpm(Mod,Func,Arity,CallFunc) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- init_tpm(Nodes,Mod,Func,Arity,CallFunc) -> {ok,NodeResults} |
- {error,Reason}
- init_tpm(Mod,Func,Arity,InitFunc,CallFunc,ReturnFunc,RemoveFunc) ->
- {ok,NodeResults} | NodeResult | {error,Reason}
- init_tpm(Nodes,Mod,Func,Arity,
- InitFunc,CallFunc,ReturnFunc,RemoveFunc) -> {ok,NodeResults} |
- {error,Reason}
- Types:
- Mod = Func = atom()
- Arity = int()
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- InitFunc,RemoveFunc = {Module,Function} | function()/4 | void
- CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
- Initializes Mod:Func/Arity for meta tracing without setting any meta
- trace patterns. This is necessary if the named match specs will be
- used (see tpm_ms/5,6). Otherwise initialization of public loop data
- can be done at the same time as setting meta trace patterns using
- tpm/8,9.
- Note that we can not use wildcards here (even if it is perfectly legal
- in Erlang). It also sets the CallFunc and ReturnFunc for the meta
- traced function. That is the functions which will be called when a
- function call and a return_trace meta trace message respectively
- arrives to the inviso meta tracer for Mod:Func/Arity.
- This function is also available without InitFunc and RemoveFunc. That
- means that no initialization of the public loop data structure will be
- done and that CallFunc and ReturnFunc must either use already existing
- parts of public loop data structure or not use it at all.
- The InitFunc initializes the already existing public loop data
- structure for use with Mod:Func/Arity. InitFunc(Mod,Func,Arity,PublLD)
- -> {ok,NewPublLD,Output} where OutPut can be a binary which will then
- be written to the trace information file. If it is not a binary, no
- output will be done. RemoveFunc will be called when the meta tracing
- is cleared with ctpm/3,4. RemoveFunc(Mod,Func,Arity,PublLD) ->
- {ok,NewPublLD}.
- See tpm/N for details on CallFunc and ReturnFunc.
- tpm(Mod,Func,Arity,MS) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- tpm(Nodes,Mod,Func,Arity,MS) -> {ok,NodeResults} | {error,Reason}
- tpm(Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} | NodeResults |
- {error,Reason}
- tpm(Nodes,Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
- {error,Reason}
- tpm(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc) ->
- {ok,NodeResults} | NodeResults | {error,Reason}
- tpm(Nodes,Mod,Func,Arity,MS, InitFunc,CallFunc,ReturnFunc,RemoveFunc)
- -> {ok,NodeResults} | {error,Reason}
- Types:
- Mod = Func = atom()
- Arity = int()
- MS = [match_spec()]
- Nodes = [Node]
- InitFunc = RemoveFunc = {Module,Function} | function()/4 | void
- CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,1} | {ok,0} | {error,Reason}1
- Activates meta-tracing in the inviso_rt_meta tracer. Except when using
- tpm/6, tpm/8 and tpm/9 the Mod:Func/Arity must first have been
- initiated using init_tpm/N. When calling several nodes, the nodes are
- called in parallel.
- CallFunc will be called every time a meta trace message arrives to the
- inviso meta tracer because of a call to Func.
- CallFunc(CallingPid,ActualArgList,PublLD) -> {ok,NewPrivLD,Output}
- where Output can be a binary or void. If it is a binary it will be
- written to the trace information file.
- ReturnFunc will be called every time a meta return_trace message
- arrives to the inviso meta tracer because of a return_trace of a call
- to Func. ReturnFunc(CallingPid,ReturnValue,PublLD) ->
- {ok,NewPrivLD,Output}. Further the ReturnFunc must handle the fact
- that a return_trace message arrives for a call which was never
- noticed. This because the message queue of the meta tracer may have
- been emptied.
- tpm_tracer(Mod,Func,Arity,MS) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- tpm_tracer(Nodes,Mod,Func,Arity,MS) -> {ok,NodeResults} |
- {error,Reason}
- tpm_tracer(Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
- NodeResults | {error,Reason}
- tpm_tracer(Nodes,Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
- {error,Reason}
- tpm_tracer(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc)
- -> {ok,NodeResults} | NodeResults | {error,Reason}
- tpm_tracer(Nodes,Mod,Func,Arity,MS,
- InitFunc,CallFunc,ReturnFunc,RemoveFunc) -> {ok,NodeResults} |
- {error,Reason}
- See tpm/X for details on arguments and return values.
- Same as tpm/X but all match specs in MS containing a trace action term
- will have a {tracer,Tracer} appended to its enable-list. Tracer will
- be the current output for regular trace messages as specified when
- tracing was initiated. This function is useful when setting a meta
- trace pattern on a function with the intent that its execution shall
- turn tracing on for the process executing the match-spec in the meta
- trace pattern. The reason the tracer process trace flag can not be
- explicitly written in the action term by the user is that it may be
- difficult to learn its exact value for a remote node. Further more
- inviso functions are made to work on several nodes at the same time,
- requiering different match specs to be set for different nodes.
- Simple example: We want any process executing the function
- mymod:init(1234) (with the argument, exactly the integer 1234) to
- begin function-call tracing. In the example, if the process is found
- to be one that shall start call tracing, we also first disable all
- process trace flags to ensure that we have full control over what the
- process traces. void in the example specifies that the meta-tracer
- (inviso_rt_meta) will not call any function when meta trace messages
- for mymod:init/1 arrives. There is no need for a CallFunc since the
- side-effect (start call-tracing) is achieved immediately with the
- match-spec.
- .. sourcecode:: erlang
-
- inviso:tpm_tracer(mymod,init,1,[{[1234],[],[{trace,[all],[call]}]}],void).
- This will internally, by the meta tracer on each Erlang node, be
- translated to:
- .. sourcecode:: erlang
-
- erlang:trace_pattern({mymod,init,1},[{[1234],[],[{trace,[all],[call,{{tracer,T}}]}]}],[{meta,P}]).
-
- Where T is the tracer for regular trace messages (most often a trace-
- port, but can be the runtime component inviso_rt process), and P is
- the meta tracer (the inviso_rt_meta process).
- tpm_ms(Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- tpm_ms(Nodes,Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
- {error,Reason}
- Types:
- Nodes = [Node]<v> <v>Mod = Func = atom()<v> <v>Arity = int()<v>
- <v>MSname = term()<v> <v>MS = [match_spec()]<v> <v>NodeResults =
- [{Node,NodeResult}]<v> <v>NodeResult = {ok,1} | {ok,0} |
- {error,Reason}<v>
- This function adds a list of match-specs to the already existing ones.
- It uses an internal database to keep track of existing match-specs.
- This set of match specs can hereafter be referred to with the name
- MSname. If the match-spec does not result in any meta traced functions
- (for whatever reason), the MS is not saved in the database. The
- previously known match-specs are not removed. If MSname is already in
- use as a name refering to a set of match-specs for this particular
- meta-traced function, the previous set of match-specs are replaced
- with MS.
- Mod:Func/Arity must previously have been initiated in order for this
- function to add a match-spec.
- When calling several nodes, the nodes are called in parallel. {ok,1}
- indicates success.
- tpm_ms_tracer(Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
- NodeResult | {error,Reason}
- tpm_ms_tracer(Nodes,Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
- {error,Reason}
- See tpm_ms/X for details on arguments and return values, and
- tpm_tracer/X for explanations about the appending of {tracer,Tracer}
- process trace flag.
- ctpm_ms(Mod,Func,Arity,MSname) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- ctpm_ms(Nodes,Mod,Func,Arity,MSname) -> {ok,NodeResults} |
- {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Removes a named match-spec from the meta traced function. Note that it
- never is a fault to remove a match spec. Not even from a function
- which is non existent.
- When calling several nodes, the nodes are called in parallel.
- ctpm(Mod,Func,Arity) -> {ok,NodeResults} | NodeResult | {error,Reason}
- ctpm(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Removes the meta trace pattern for the function, means stops
- generating output for this function. The public loop data structure
- may be cleared by the previously entered RemoveFunc.
- When calling several nodes, the nodes are called in parallel.
- tpm_localnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
- tpm_localnames(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {R1,R2}
- R1 = R2 = {ok,0} | {ok,1} | {error,Reason}
- Quick version for setting meta-trace patterns on erlang:register/2. It
- uses a default CallFunc and ReturnFunc in the meta-tracer server. The
- main purpose of this function is to create ti-log entries for
- associations between pids and registered name aliases. The
- implementation uses return_trace to see if the registration was
- successful or not, before actually making the ti-log alias entry.
- Further the implementation also meta traces the BIF unregister/1.
- If both N1 and N2 is 1, function call was successful. N1 and N2
- represent setting meta trace pattern on register/2 and unregister/1.
- ctpm_localnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
- ctpm_localnames(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {R1,R2}
- R1 = R2 = ok | {error,Reason}
- Function for removing previously set patters by tpm_localnames/0. The
- two results R1 and R2 represents that meta pattern is removed from
- both register/2 and unregister/1.
- tpm_globalnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
- tpm_globalnames(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {R1,R2}
- R1 = R2 = {ok,0} | {ok,1} | {error,Reason}
- Quick version for setting meta-trace patterns capable of learning the
- association of a pid with a globally registered name (registered using
- global:register_name). The implementation meta-traces on
- global:handle_call({register,'_','_','_'},'_','_') and
- global:delete_global_name/2. The N1 and N2 represents the success of
- the two sub-tmp calls.
- ctpm_globalnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
- ctpm_globalnames(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {R1,R2} | {error,Reason}
- R1 = R2 = ok | {error,Reason}
- Function for removing previously set meta patters by
- tpm_globalnames/0,1. The two results R1 and R2 represents that meta
- pattern are removed from both global:handle_call/3 and
- global:delete_global_name/1.
- ctp_all() -> {ok,NodeResults} | NodeResult | {error,Reason}
- ctp_all(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Clears all, both global and local trace patterns. Does not clear meta
- trace patterns. Equivalent to a call to ctp/3,4 and to ctpl/3,4 with
- wildcards '_' for all modules, functions and arities.
- suspend(SReason) -> {ok,NodeResults} | NodeResult | {error,Reason}
- suspend(Nodes,SReason) -> {ok,NodeResults} | {error,Reason}
- Types:
- SReason = term()
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Suspends the runtime components. SReason will become the suspend-
- reason replied in for instance a get_status/0,1 call. A runtime
- component that becomes suspended removes all trace flags and all meta
- trace patterns. In that way trace output is no longer generated. The
- task of reactivating a suspended runtime component is outside the
- scoop of inviso. It can for instance be implemented by a higher layer
- trace-tool "remembering" all trace flags and meta patterns set.
- cancel_suspension() -> {ok,NodeResults} | NodeResult | {error,Reason}
- cancel_suspend(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = ok | {error,Reason}
- Makes the runtime components running again (as opposite to suspended).
- Since reactivating previous trace flags and meta trace patterns is
- outside the scoop of inviso, cancelling suspension is simply making it
- possible to set trace flags and meta trace patterns again.
- get_status() -> {ok,NodeResults} | NodeResult | {error,Reason}
- get_status(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,{State,Status}} | {error,Reason}
- State = new | idle | tracing
- Status = running | {suspended,SReason}
- SReason = term()
- Finds out the state and status of a runtime component. A runtime
- component is in state new before it has been initiated to do any
- tracing the first time. There are clear-functions which can make a
- runtime component become new again without having to restart. A
- runtime component becomes idle after tracing is stopped.
- get_tracerdata() -> {ok,NodeResults} | NodeResult | {error,Reason}
- get_tracerdata(Nodes) -> {ok,NodeResults} | {error,Reason}
- Types:
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,NResult} | {error,Reason}
- NResult = TracerData | no_tracerdata
- Returns the current tracerdata of a runtime component. A runtime
- component in state new can not have tracerdata. An idle runtime
- component does have tracerdata, the last active tracerdata. TracerData
- will be a term as specified to init_tracing when tracing was initiated
- for the runtime component.
- list_logs() -> {ok,NodeResults} | NodeResult | {error,Reason}
- list_logs(Nodes) -> {ok,NodeResults} | {error,Reason}
- list_logs(NodeTracerData) -> {ok,NodeResults} | {error,Reason}
- list_logs(TracerData) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- Types:
- TracerData -- see init_tracing/1,2
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,FileList} | {ok,no_log} | {error,Reason}
- FileList = [FileType]
- FileType = {trace_log,Dir,Files} | {ti_log,Dir,Files}
- Files = [FileNameWithOutPath]
- Returns the actually existing log files associated with TracerData. If
- a tracerdata is not specified, current tracerdata is used for that
- particular runtime component. Files will be a list of one or more
- files should it be a wrap-set. Otherwise the it is a list of only one
- filename.
- This function is useful to learn the name and path of all files
- belonging to a trace. This information can later be used to move those
- files for merging. Note that since it is possible to ask on other
- tracerdata than the current, it is possible to learn filenames of
- previously done traces, under the circumstances that they have not
- been removed.
- fetch_log(LogSpecList,DestDir,Prefix) -> {ok,NodeResults} |
- {error,not_distributed} | {error,Reason}
- fetch_log(DestDir,Prefix) -> {ok,NodeResults} |
- {error,not_distributed} | {error,Reason}
- Types:
- DestDir = string()
- Prefix = string()
- LogSpecList = [LogSpec]
- LogSpec = {Node,FileSpecList} | Node | {Node,TracerData}
- TracerData = see init_tracing/1,/2
- FileSpecList = [{trace_log,Dir,FileList},{ti_log,Dir,FileList}] |
- [{trace_log,Dir,FileList}]
- FileList = [RemoteFileName]
- NodeResult = {Conclusion,ResultFileSpec} | no_log | {error,NReason}
- NReason = own_node | Reason
- Conclusion = complete | incomplete
- ResultFileSpec = [{trace_log,FileResults},{ti_log,FileResults}]
- FileResults = [FileResult]
- FileResult = {ok,FileName} | {error,FReason}
- FReason = {file_open,{posix(),FileName}} |
- {file_open,{posix(),RemoteFileName}} |
- {file_open,{posix(),[DestDir,Prefix,RemoteFileName]}} |
- {file_write,{posix(),FileName}} | {truncated,FileName} |
- {truncated,{Reason,FileName}}
- posix() = atom()
- Copies log files over distributed erlang to the control component
- node. This function can only be used in a distributed system.
- The resulting transferred files will have the prefix Prefix and will
- be located in DestDir. The source files can either be pointed out
- using a FileListSpec or tracerdata. If no files are explicitly
- specified, current tracerdata for that node will be used. Note that if
- source files have the same name (on several nodes) they will overwrite
- each other at DestDir.
- delete_log(Nodes,TracerData) -> {ok,NodeResults} | {error,Reason}
- delete_log(NodeSpecList) -> {ok,NodeResults} | {error,Reason}
- delete_log(Spec) -> {ok,NodeResults} | NodeResult | {error,Reason}
- delete_log(TracerData) -> {ok,NodeResults} | NodeResult |
- {error,Reason}
- delete_log() -> {ok,NodeResults} | NodeResult | {error,Reason}
- Types:
- Nodes = [Node]
- NodeSpecList = [{Node,Spec}]
- Spec = [AbsPathFileName] | LogSpecs
- LogSpecs = [LogSpec]
- LogSpec = {trace_log,Dir,[FileNameWithoutPath]} |
- {ti_log,Dir,[FileNameWithoutPath]}
- TracerData -- see init_tracing/1,/2
- NodeResults = [{Node,NodeResult}]
- NodeResult = {ok,no_log} | {ok,LogInfos} | {ok,FileInfos}
- LogInfos = [LogInfo]
- LogInfo = {trace_log,FileInfos} | {ti_log,FileInfos}
- FileInfos = [FileInfo]
- FileInfo = {ok,FileName} | {error,Reason}
- Deletes listed files or files corresponding to tracerdata. If no
- tracerdata or list of files are specified in the call, current
- tracerdata at the runtime components will be used to identify files to
- delete. All filenames shall be strings.
- FileName can either be an absolute path or just a filename depending
- on if AbsPathFileName or a LogSpec was used to identify the file.
- subscribe() -> ok | {error,Reason}
- subscribe(Pid) -> ok | {error,Reason}
- Types:
- Pid = pid()
- Adds Pid or self() if using subscribe/0 to the inviso-event sending
- list. Note that it is possible to add a pid several times and that the
- Pid then will receive multiple copies of inviso-event messages.
- All events will be sent to all subscribers in the event sending list.
- .. sourcecode:: erlang
-
- Event = {inviso_event,ControllerPid,erlang:localtime(),Msg}
- Msg = {connected, Node, {RTtag, {State,Status}}}
- | {disconnected, Node, NA}
- | {state_change,Node,{State,Status}}
- | {port_down,Node,Reason}
- Node = node() | local_runtime
-
- Subscribing to inviso-event may be necessary for a higher layer trace-
- tool using inviso to follow the runtime components. local_runtime will
- be used for a runtime component running in a non-distributed
- environment.
- unsubscribe() -> ok
- unsubscribe(Pid) -> ok
- Removes Pid (once) from the subscription list.
- inviso 0.6
- Copyright Š 1991-2009 `Ericsson AB
- <http://www.ericsson.com/technology/opensource/erlang>`__