PageRenderTime 80ms CodeModel.GetById 60ms app.highlight 14ms RepoModel.GetById 0ms app.codeStats 1ms

HTML | 850 lines | 843 code | 7 blank | 0 comment | 0 complexity | 95f10ef37bb460071121ccc623f9c152 MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  2  "">
  4<html xmlns="">
  5  <head>
  6    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  8    <title>Lib - Inviso-0.6 - Doc - Html - Inviso &mdash; Erlang/OTP vR13B02 documentation</title>
  9    <link rel="stylesheet" href="../../../../_static/default.css" type="text/css" />
 10    <link rel="stylesheet" href="../../../../_static/pygments.css" type="text/css" />
 11    <script type="text/javascript">
 13        URL_ROOT:    '../../../../',
 14        VERSION:     'R13B02',
 15        COLLAPSE_MODINDEX: false,
 16        FILE_SUFFIX: '.html',
 17        HAS_SOURCE:  true
 18      };
 19    </script>
 20    <script type="text/javascript" src="../../../../_static/jquery.js"></script>
 21    <script type="text/javascript" src="../../../../_static/doctools.js"></script>
 22    <link rel="top" title="Erlang/OTP vR13B02 documentation" href="../../../../index.html" /> 
 23  </head>
 24  <body>
 25    <div class="related">
 26      <h3>Navigation</h3>
 27      <ul>
 28        <li class="right" style="margin-right: 10px">
 29          <a href="../../../../genindex.html" title="General Index"
 30             accesskey="I">index</a></li>
 31        <li><a href="../../../../index.html">Erlang/OTP vR13B02 documentation</a> &raquo;</li> 
 32      </ul>
 33    </div>  
 35    <div class="document">
 36      <div class="documentwrapper">
 37        <div class="bodywrapper">
 38          <div class="body">
 40  <div class="section" id="lib-inviso-0-6-doc-html-inviso">
 41<h1>Lib - Inviso-0.6 - Doc - Html - Inviso<a class="headerlink" href="#lib-inviso-0-6-doc-html-inviso" title="Permalink to this headline"></a></h1>
 42<p>` &lt;<a class="reference external" href=""></a>&gt;`__</p>
 43<div class="section" id="inviso">
 44<h2>inviso<a class="headerlink" href="#inviso" title="Permalink to this headline"></a></h2>
 45<div class="section" id="module">
 46<h3>MODULE<a class="headerlink" href="#module" title="Permalink to this headline"></a></h3>
 49<div class="section" id="module-summary">
 50<h3>MODULE SUMMARY<a class="headerlink" href="#module-summary" title="Permalink to this headline"></a></h3>
 51<p>Main API Module to the Inviso Tracer</p>
 53<div class="section" id="description">
 54<h3>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline"></a></h3>
 55<p>With the inviso API runtime components can be started and tracing
 56managed across a network of distributed Erlang nodes, using a control
 57component also started with inviso API functions.</p>
 58<p>Inviso can be used both in a distributed environment and in a non-
 59distributed. API functions not taking a list of nodes as argument
 60works on all started runtime components. If it is the non-distributed
 61case, that is the local runtime component. The API functions taking a
 62list of nodes as argument, or as part of one of the arguments, can not
 63be used in a non-distributed environment. Return values named
 64NodeResult refers to return values from a single Erlang node, and will
 65therefore be the return in the non-distributed environment.</p>
 67<div class="section" id="exports">
 68<h3>EXPORTS<a class="headerlink" href="#exports" title="Permalink to this headline"></a></h3>
 69<p>start() -&gt; {ok,pid()} | {error,Reason}
 70start(Options) -&gt; {ok,pid()} | {error,Reason}</p>
 72<p>Options = [Option]</p>
 73<p>Options may contain both options which will be default options to a
 74runtime component when started, and options to the control component.
 75See add_nodes/3 for details on runtime component options. The control
 76component recognizes the following options:</p>
 77<table class="docutils field-list" frame="void" rules="none">
 78<col class="field-name" />
 79<col class="field-body" />
 80<tbody valign="top">
 81<tr class="field"><th class="field-name" colspan="2">{subscribe,Pid}:</th></tr>
 82<tr><td>&nbsp;</td><td class="field-body">Making the process Pid receive Inviso events from
 83the control component. Starts a control component process on the local
 84node. A control component must be started before runtime components
 85can be started manually or otherwise accessed through the inviso API.</td>
 89<p>stop() -&gt; shutdown</p>
 90<p>Stops the control component. Runtime components are left as is. They
 91will behave according to their dependency values.</p>
 92<p>add_node(RTtag) -&gt; NodeResult | {error,Reason}
 93add_node(RTtag,Options) -&gt; NodeResult | {error,Reason}</p>
 95<p>RTtag = PreviousRTtag = term()
 96Options = [Option]
 97?Option &#8211; see below
 98?Option = {dependency,Dep}
 99??Dep = int() | infinity</p>
100<p>The timeout, in milliseconds, before the runtime component will
101terminate if abandoned by this control component. ?Option =
102{overload,Overload} | overload
103Controls how and how often overload checks shall be performed. Just
104overloadspecifies that no loadcheck shall be performed. ??Overload =
105Interval | {LoadMF,Interval,InitMFA,RemoveMFA}
106???LoadMF = {Mod,Func} | function()/1
107???Interval = int() | infinity
108Interval is the time in milliseconds between overload checks.
109???InitMFA = RemoveMFA = {Mod,Func,ArgList} | void
110When starting up the runtime component or when changing options (see
111change_options/2) the overload mechanism is initialized with a call to
112the InitMFAfunction. It shall return LoadCheckData. Every time a load
113check is performed, LoadMFis called with LoadCheckDataas its only
114argument. LoadMFshall return okor {suspend,Reason}. When the runtime
115component is stopped or made to change options involving changing
116overload-check, the RemoveMFAfunction is called. Its return value is
117discarded. NodeResult = {ok,NAns} | {error,Reason}
118?NAns = new | {adopted,State,Status,PreviousRTtag} | already_added
119??State = new | tracing | idle
120??Status = running | {suspended,SReason}</p>
121<p>Starts or tries to connect to an existing runtime component at the
122local node, regardless if the system is distributed or not. Options
123will override any default options specified at start-up of the control
125<p>The PreviousRTtag can indicate if the incarnation of the runtime
126component at the node in question was started by &#8220;us&#8221; and then can be
127expected to do tracing according to &#8220;our&#8221; instructions or not.</p>
128<p>add_node_if_ref(RTtag) -&gt; NodeResult |
129{error,{wrong_reference,OtherTag}} | {error,Reason}
130add_node_if_ref(RTtag,Options) -&gt; NodeResult |
131{error,{wrong_reference,OtherRef}} | {error,Reason}</p>
133<p>OtherRef = term()</p>
134<p>rttag of the running incarnation
135As add_node/1,2 but will only adopt the runtime component if its rttag
136is RTtag.</p>
137<p>add_nodes(Nodes,RTtag) -&gt; {ok,NodeResults} | {error,Reason}
138add_nodes(Nodes,RTtag,Options) -&gt; {ok,NodeResults} | {error,Reason}</p>
140<p>Nodes = [Node]
141NodeResults = [{Node,NodeResult}]</p>
142<p>As add_node/1,2 but for a distributed environment.</p>
143<p>add_nodes_if_ref(Nodes,RTtag) -&gt; NodeResult | {error,Reason}
144add_nodes_if_ref(Nodes,RTtag,Options) -&gt; NodeResult | {error,Reason}</p>
146<p>Nodes = [Node]
147NodeResults = [{Node,NodeResult}]</p>
148<p>As add_node_if_ref/1,2 but for a distributed environment.</p>
149<p>stop_nodes() -&gt; {ok,NodeResults} | NodeResult
150stop_nodes(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
152<p>NodeResults = [{Node,NodeResult}]
153NodeResult = ok | {error,Reason}</p>
154<p>Stops runtime component on Nodes. stop_nodes/0 will if the control
155component is running on a distributed node stop all runtime
156components. And if running on a non distributed node, stop the local
157and only runtime component.</p>
158<p>stop_all() = {ok,NodeResults} | NodeResult</p>
160<p>NodeResults = [{Node,NodeResult}]
161NodeResult = ok | {error,Reason}</p>
162<p>A combination of stop/0 and stop_nodes/0.</p>
163<p>change_options(Options) -&gt; NodeResult | {ok,NodeResults} |
165change_options(Nodes,Options) -&gt; {ok,NodeResults} | {error,Reason}</p>
167<p>Nodes = [Node]
168NodeResults = [{Node,NodeResult}]
169NodeResult = ok | {error,Reason}</p>
170<p>Changes the options for one or several runtime components. If for
171instance overload is redefined, the previous overload will be stopped
172and the new started. See add_node/1 for details on Options.</p>
173<p>init_tracing(TracerData) -&gt; {ok,NodeResults} | NodeResult |
175init_tracing(TracerList) -&gt; {ok,NodeResults} | {error,Reason}
176init_tracing(Nodes,TracerData) -&gt; {ok,NodeResults} | {error,Reason}</p>
178<p>TracerData = [{trace,LogTD} [,{ti,TiTD}] }] | LogTD
179LogTD = {HandlerFun,Data1} | collector | {relayer,CollectingNode} |
180{ip,IPPortParameters} | {file,FilePortParameters}
181TiTD = {file,FileName} | {file,FileName,TiSpec} | {relay,Node}
182?TiSpec = {InitMFA,RemoveMF,CleanMF}
183??InitMFA = {Mi,Fi,Argsi}
184??RemoveMF = {Mr,Fr} | void
185??CleanMF = {Mc,Fc}
186??Mi = Fi = Mr = Fr = Mc = Fd = atom()
187??Argsi = [term()]
188TracerList = [{Node,TracerData}]
189IPPortParameters = Portno | {Portno,Qsize}
190?Portno = tcp_portno()
191?Qsize = int()
192FilePortParameters = {Filename,wrap,Tail,{time,WrapTime},WrapCnt} |
193{FileName,wrap,Tail,WrapSize,WrapCnt} | {FileName,wrap,Tail,WrapSize}
194| {FileName,wrap,Tail} | FileName
195?FileName = string()
196?Tail = string() =/= &#8220;&#8221;
197?WrapTime = WrapCnt = WrapSize = int() &gt;0
198TracerList = [{Node,TracerData}]
199Nodes = [Node]
200HandlerFun = function()/2;
201?HandlerFun(TraceMsg,Data1) -&gt; NewData
202CollectingNode = pid() | node()
203NodeResults = [{Node,NodeResult}]
204NodeResult = {ok,LogResults} | {error,NReason}
205?LogResults = [LogResult]
206??LogResult = {trace_log,LogRes} | {ti_log,LogRes}
207???LogRes = ok | {error,Reason}</p>
208<p>Starts the tracing at the specified nodes, meaning that the runtime
209components transits from the state new or idle to tracing. For trace
210messages to be generated, there must of course also be trace pattern
211and/or trace flags set. Such can not be set before tracing has been
212initiated with init_tracing/1,2.</p>
213<p>TracerData controls how the runtime component will handle generated
214trace messages. The trace tag controls how regular trace messages are
215handled. The ti tag controls if and how trace information will be
216stored and the meta tracer will be activated. That is if ti is
217omitted, no meta tracer will be started as part of the runtime
218component. It is possible to have ti without trace, but most likely
219not useful.</p>
220<p>The ip and file trace tracerdata instructions results in using the
221built in trace ip-port and file-port respectively. relayer will result
222in that all regular trace messages are forwarded to a runtime
223component at the specified node. Using a HandlerFun will result in
224that every incoming regular trace message is applied to the
225HandlerFun. collector can be used to use this runtime component to
226receive relayed trace messages and print them to the shell.</p>
227<p>The trace information can be configured to either write trace
228information to a plain trace information file or to relay it to
229another inviso meta tracer on another node. The inviso meta tracer is
230capable of matching function calls with their function returns (only
231if return_trace is activated in the meta trace match specification for
232the function in question). This is necessary since it may not be
233possible to decide what to do, if anything shall be done at all, until
234the return value of the function call is examined.</p>
235<p>To be able to match calls with returns a state can be saved when
236detecting a function call in a public loop data structure kept by the
237inviso meta tracer. The public loop data structure is given as
238argument to a handler-function called whenever a meta trace message
239arrives to the inviso meta tracer (both function calls and function
240returns). The public loop data structure is first initiated by the
241Mi:Fi function which takes the items in Argsi as arguments. Fi shall
242return the initial public loop data structure. When meta tracing is
243stopped, either because tracing is stopped or because tracing is
244suspended, the Mr:Fr(PublicLoopData) is called to offer a possibility
245to clean-up. Note that for every function meta-tracing is activated, a
246public loop data modification function can be speficied. That function
247will prepare the current loop data structure for this particular
249<p>Further there is a risk that function call states becomes abandoned
250inside the public loop data structure. This will happen if a function
251call is entered into the public loop data structure, but no function
252return occurs. To prevent the public loop data structure from growing
253infinitely the clean function Fc will periodically be called with the
254public loop data structure as argument. Elements entered into the
255public loop data structure as a result of a function call must contain
256a timestamp for the Fc to be able to conclude if it is abandoned or
257not. Fc shall return a new public loop data structure.</p>
258<p>When initiating tracing involving trace information without a TiSpec,
259a default public loop data structure will be initiated to handle
260locally registered process aliases. The default public loop data
261structure is a two-tuple where the first element is used by the meta
262tracing on the BIF register/2. The second element is left for user
264<p>The default public loop data structure may be extended with more
265element positions. The first position must be left to the
266implementation of registered-name translations. If the public loop
267data structure is changed no longer meeting this requirement, the
268tpm_localnames/0,1 and tpm_globalnames/0,1 can no longer be used.</p>
269<p>A wrap files specification is used to limit the disk space consumed by
270the trace. The trace is written to a limited number of files each with
271a limited size. The actual filenames are Filename ++ SeqCnt ++ Tail,
272where SeqCnt counts as a decimal string from 0 to WrapCnt and then
273around again from 0. When a trace message written to the current file
274makes it longer than WrapSize, that file is closed, if the number of
275files in this wrap trace is as many as WrapCnt the oldest file is
276deleted then a new file is opened to become the current. Thus, when a
277wrap trace has been stopped, there are at most WrapCnt trace files
278saved with a size of at least WrapSize (but not much bigger), except
279for the last file that might even be empty. The default values are
280WrapSize == 128*1024 and WrapCnt == 8.</p>
281<p>The SeqCnt values in the filenames are all in the range 0 through
282WrapCnt with a gap in the circular sequence. The gap is needed to find
283the end of the trace.</p>
284<p>If the WrapSize is specified as {time,WrapTime}, the current file is
285closed when it has been open more than WrapTime milliseconds,
286regardless of it being empty or not.</p>
287<p>The ip trace driver has a queue of QSize messages waiting to be
288delivered. If the driver cannot deliver messages as fast as they are
289produced by the runtime system, they are dropped. The number of
290dropped messages are indicated in the trace log as separate trace
292<p>stop_tracing(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
293stop_tracing() -&gt; {ok,NodeResults} | NodeResult</p>
295<p>Nodes = [Node]
296NodeResults = [{Node,NodeResult}]
297NodeResult = {ok,State} | {error,Reason}
298?State = new | idle</p>
299<p>Stops tracing on all or specified Nodes. Flushes the trace buffer if a
300trace-port is used, closes the trace-port and removes all trace flags
301and meta-patterns. The nodes are called in parallel.</p>
302<p>Stopping tracing means going to state idle&lt;c&gt;. If the runtime
303component was already in state &lt;c&gt;new, it will of course remain in
304state new (then there was no tracing to stop).</p>
305<p>clear() -&gt; {ok,NodeResults} | NodeResult
306clear(Nodes,Options) -&gt; {ok,NodeResults} | {error,Reason}
307clear(Options) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
309<p>Nodes = [Node]
310Options = [Option]
311?Option = keep_trace_patterns | keep_log_files
312NodeResults = [{Node,NodeResult}]
313?NodeResult = {ok,{new,Status}} | {error,Reason}
314??Status = running | {suspended,SReason}</p>
315<p>Stops all tracing including removing meta-trace patterns. Removes all
316trace patterns. If the node is tracing or idle, trace-logs belonging
317to the current tracerdata are removed. Hence the node is returned to
318state new. Note that the node can still be suspended.</p>
319<p>Various options can make the node keep set trace patterns and log-
320files. The node still enters the new state.</p>
321<p>tp(Nodes,Mod,Func,Arity,MatchSpec,Opts) -&gt;
322tp(Nodes,Mod,Func,Arity,MatchSpec) -&gt; {ok,NodeResults} |
324tp(Mod,Func,Arity,MatchSpec,Opts) -&gt;
325tp(Mod,Func,Arity,MatchSpec) -&gt; {ok,NodeResults} | NodeResult |
327tp(Nodes,PatternList) -&gt; {ok,NodeResults} | {error,Reason}
328tp(PatternList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
330<p>Nodes = [Node]
331Mod = Func = atom() | &#8216;_&#8217;
332Arity = int() | &#8216;_&#8217;
333MatchSpec = true | false | [] | matchspec()
334PatternList = [Pattern],
335?Pattern = {Mod,Func,Arity,MatchSpec,Opts}
336Opts = [Opt]
337?Opt = only_loaded
338NodeResults = [NodeResult]
339?NodeResult = {ok,[Ans]} | {error,Reason}
340??Ans = int() | {error,Reason}</p>
341<p>Set trace pattern (global) on specified or all nodes. The integer
342replied if the call was successfully describes the number of matched
343functions. The functions without a Nodes argument means all nodes, in
344a non-distributed environment it means the local node. Using wildcards
345follows the rules for wildcards of erlang:trace_pattern/3. It is for
346instance illegal to specify M == &#8216;_&#8217; while F is not &#8216;_&#8217;.</p>
347<p>When calling several nodes, the nodes are called in parallel.</p>
348<p>The option only_loaded will prevent modules not loaded (yet) into the
349runtime system to become loaded just as a result of that a trace
350pattern is requested to be set on it. Otherwise modules are
351automatically loaded if not already loaded (since the module must be
352present for a trace pattern to be set on it). The latter does not
353apply if the wildcard &#8216;_&#8217; is used as module specification.</p>
354<p>tpl(Nodes,Mod,Func,Arity,MatchSpec) -&gt;
355tpl(Nodes,Mod,Func,Arity,MatchSpec,Opts) -&gt; {ok,NodeResults} |
357tpl(Mod,Func,Arity,MatchSpec) -&gt;
358tpl(Mod,Func,Arity,MatchSpec,Opts) -&gt; {ok,NodeResults} | NodeResult|
360tpl(Nodes,PatternList) -&gt; {ok,NodeResults} | {error,Reason}
361tpl(PatternList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
362<p>See tp/N function above for details on arguments and return values.</p>
363<p>Set local trace pattern on specified functions. When calling several
364nodes, the nodes are called in parallel.</p>
365<p>ctp(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}
366ctp(Mod,Func,Arity) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
367<p>See tp/N for argument descriptions.</p>
368<p>Clear global trace patterns. When calling several nodes, the nodes are
369called in parallel.</p>
370<p>ctpl(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}
371ctpl(Mod,Funct,Arity) -&gt; {ok,NodeResults} | NodeResult |
373<p>See tp/N for argument description.</p>
374<p>Clear local trace patterns. When calling several nodes, the nodes are
375called in parallel.</p>
376<p>tf(Nodes,PidSpec,FlagList) -&gt; {ok,NodeResults} | {error,Reason}
377tf(PidSpec,FlagList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
378tf(Nodes,TraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
379tf(NodeTraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
380tf(TraceConfList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
382<p>Nodes = [Node]
383NodeTraceConfList = [{Node,TraceConfList}]
384TraceConfList = [{PidSpec,FlagList}]
385FlagList = [Flag]
386PidSpec = all | new| existing | pid() | locally_registered_name()
387Flag &#8211; see erlang:trace/3
388NodeResult = {ok,[Ans]} | {error,Reason}
389Ans = int() | {error,Reason}</p>
390<p>Set process trace flags on processes on all or specified nodes. The
391integer returned if the call was successful describes the matched
392number of processes. The functions without a Nodes argument means all
393nodes, in a non-distributed environment it means the local node.</p>
394<p>There are many combinations which does not make much sense. For
395instance specifying a certain process identifier at all nodes. Or an
396empty TraceConfList for all nodes.</p>
397<p>When calling several nodes, the nodes are called in parallel.</p>
398<p>ctf(Nodes,PidSpec,FlagList) -&gt; {ok,NodeResults} | {error,Reason}
399ctf(PidSpec,FlagList) -&gt; {ok,NodeResults} | NodeResult |
401ctf(Nodes,TraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
402ctf(TraceConfList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
403<p>See tf/N for arguments and return value description.</p>
404<p>Clear process trace flags on all or specified nodes. When calling
405several nodes, the nodes are called in parallel.</p>
406<p>ctf_all(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
407ctf_all() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
409<p>Nodes = [Node]
410NodeResults = [{Node,NodeResult}]
411NodeResult = ok | {error,Reason}</p>
412<p>Clears all trace flags on all or specified nodes. Just for
414<p>init_tpm(Mod,Func,Arity,CallFunc) -&gt; {ok,NodeResults} | NodeResult |
416init_tpm(Nodes,Mod,Func,Arity,CallFunc) -&gt; {ok,NodeResults} |
418init_tpm(Mod,Func,Arity,InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt;
419{ok,NodeResults} | NodeResult | {error,Reason}
421InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt; {ok,NodeResults} |
424<p>Mod = Func = atom()
425Arity = int()
426NodeResults = [{Node,NodeResult}]
427NodeResult = ok | {error,Reason}
428InitFunc,RemoveFunc = {Module,Function} | function()/4 | void
429CallFunc = ReturnFunc = {Module,Function} | function()/3 | void</p>
430<p>Initializes Mod:Func/Arity for meta tracing without setting any meta
431trace patterns. This is necessary if the named match specs will be
432used (see tpm_ms/5,6). Otherwise initialization of public loop data
433can be done at the same time as setting meta trace patterns using
435<p>Note that we can not use wildcards here (even if it is perfectly legal
436in Erlang). It also sets the CallFunc and ReturnFunc for the meta
437traced function. That is the functions which will be called when a
438function call and a return_trace meta trace message respectively
439arrives to the inviso meta tracer for Mod:Func/Arity.</p>
440<p>This function is also available without InitFunc and RemoveFunc. That
441means that no initialization of the public loop data structure will be
442done and that CallFunc and ReturnFunc must either use already existing
443parts of public loop data structure or not use it at all.</p>
444<p>The InitFunc initializes the already existing public loop data
445structure for use with Mod:Func/Arity. InitFunc(Mod,Func,Arity,PublLD)
446-&gt; {ok,NewPublLD,Output} where OutPut can be a binary which will then
447be written to the trace information file. If it is not a binary, no
448output will be done. RemoveFunc will be called when the meta tracing
449is cleared with ctpm/3,4. RemoveFunc(Mod,Func,Arity,PublLD) -&gt;
451<p>See tpm/N for details on CallFunc and ReturnFunc.</p>
452<p>tpm(Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | NodeResult |
454tpm(Nodes,Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | {error,Reason}
455tpm(Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} | NodeResults |
457tpm(Nodes,Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
459tpm(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt;
460{ok,NodeResults} | NodeResults | {error,Reason}
461tpm(Nodes,Mod,Func,Arity,MS, InitFunc,CallFunc,ReturnFunc,RemoveFunc)
462-&gt; {ok,NodeResults} | {error,Reason}</p>
464<p>Mod = Func = atom()
465Arity = int()
466MS = [match_spec()]
467Nodes = [Node]
468InitFunc = RemoveFunc = {Module,Function} | function()/4 | void
469CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
470NodeResults = [{Node,NodeResult}]
471NodeResult = {ok,1} | {ok,0} | {error,Reason}1</p>
472<p>Activates meta-tracing in the inviso_rt_meta tracer. Except when using
473tpm/6, tpm/8 and tpm/9 the Mod:Func/Arity must first have been
474initiated using init_tpm/N. When calling several nodes, the nodes are
475called in parallel.</p>
476<p>CallFunc will be called every time a meta trace message arrives to the
477inviso meta tracer because of a call to Func.
478CallFunc(CallingPid,ActualArgList,PublLD) -&gt; {ok,NewPrivLD,Output}
479where Output can be a binary or void. If it is a binary it will be
480written to the trace information file.</p>
481<p>ReturnFunc will be called every time a meta return_trace message
482arrives to the inviso meta tracer because of a return_trace of a call
483to Func. ReturnFunc(CallingPid,ReturnValue,PublLD) -&gt;
484{ok,NewPrivLD,Output}. Further the ReturnFunc must handle the fact
485that a return_trace message arrives for a call which was never
486noticed. This because the message queue of the meta tracer may have
487been emptied.</p>
488<p>tpm_tracer(Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | NodeResult |
490tpm_tracer(Nodes,Mod,Func,Arity,MS) -&gt; {ok,NodeResults} |
492tpm_tracer(Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
493NodeResults | {error,Reason}
494tpm_tracer(Nodes,Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
497-&gt; {ok,NodeResults} | NodeResults | {error,Reason}
499InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt; {ok,NodeResults} |
501<p>See tpm/X for details on arguments and return values.</p>
502<p>Same as tpm/X but all match specs in MS containing a trace action term
503will have a {tracer,Tracer} appended to its enable-list. Tracer will
504be the current output for regular trace messages as specified when
505tracing was initiated. This function is useful when setting a meta
506trace pattern on a function with the intent that its execution shall
507turn tracing on for the process executing the match-spec in the meta
508trace pattern. The reason the tracer process trace flag can not be
509explicitly written in the action term by the user is that it may be
510difficult to learn its exact value for a remote node. Further more
511inviso functions are made to work on several nodes at the same time,
512requiering different match specs to be set for different nodes.</p>
513<p>Simple example: We want any process executing the function
514mymod:init(1234) (with the argument, exactly the integer 1234) to
515begin function-call tracing. In the example, if the process is found
516to be one that shall start call tracing, we also first disable all
517process trace flags to ensure that we have full control over what the
518process traces. void in the example specifies that the meta-tracer
519(inviso_rt_meta) will not call any function when meta trace messages
520for mymod:init/1 arrives. There is no need for a CallFunc since the
521side-effect (start call-tracing) is achieved immediately with the
523<div class="highlight-erlang"><div class="highlight"><pre><span class="nn">inviso</span><span class="p">:</span><span class="n">tpm_tracer</span><span class="p">(</span><span class="n">mymod</span><span class="p">,</span><span class="n">init</span><span class="p">,</span><span class="mi">1</span><span class="p">,[{[</span><span class="mi">1234</span><span class="p">],[],[{</span><span class="nb">trace</span><span class="p">,[</span><span class="n">all</span><span class="p">],[</span><span class="n">call</span><span class="p">]}]}],</span><span class="n">void</span><span class="p">).</span>
526<p>This will internally, by the meta tracer on each Erlang node, be
527translated to:</p>
528<div class="highlight-erlang"><div class="highlight"><pre><span class="nn">erlang</span><span class="p">:</span><span class="nb">trace_pattern</span><span class="p">({</span><span class="n">mymod</span><span class="p">,</span><span class="n">init</span><span class="p">,</span><span class="mi">1</span><span class="p">},[{[</span><span class="mi">1234</span><span class="p">],[],[{</span><span class="nb">trace</span><span class="p">,[</span><span class="n">all</span><span class="p">],[</span><span class="n">call</span><span class="p">,{{</span><span class="n">tracer</span><span class="p">,</span><span class="nv">T</span><span class="p">}}]}]}],[{</span><span class="n">meta</span><span class="p">,</span><span class="nv">P</span><span class="p">}]).</span>
531<p>Where T is the tracer for regular trace messages (most often a trace-
532port, but can be the runtime component inviso_rt process), and P is
533the meta tracer (the inviso_rt_meta process).</p>
534<p>tpm_ms(Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} | NodeResult |
536tpm_ms(Nodes,Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
539<p>Nodes = [Node]&lt;v&gt; &lt;v&gt;Mod = Func = atom()&lt;v&gt; &lt;v&gt;Arity = int()&lt;v&gt;
540&lt;v&gt;MSname = term()&lt;v&gt; &lt;v&gt;MS = [match_spec()]&lt;v&gt; &lt;v&gt;NodeResults =
541[{Node,NodeResult}]&lt;v&gt; &lt;v&gt;NodeResult = {ok,1} | {ok,0} |
543<p>This function adds a list of match-specs to the already existing ones.
544It uses an internal database to keep track of existing match-specs.
545This set of match specs can hereafter be referred to with the name
546MSname. If the match-spec does not result in any meta traced functions
547(for whatever reason), the MS is not saved in the database. The
548previously known match-specs are not removed. If MSname is already in
549use as a name refering to a set of match-specs for this particular
550meta-traced function, the previous set of match-specs are replaced
551with MS.</p>
552<p>Mod:Func/Arity must previously have been initiated in order for this
553function to add a match-spec.</p>
554<p>When calling several nodes, the nodes are called in parallel. {ok,1}
555indicates success.</p>
556<p>tpm_ms_tracer(Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
557NodeResult | {error,Reason}
558tpm_ms_tracer(Nodes,Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
560<p>See tpm_ms/X for details on arguments and return values, and
561tpm_tracer/X for explanations about the appending of {tracer,Tracer}
562process trace flag.</p>
563<p>ctpm_ms(Mod,Func,Arity,MSname) -&gt; {ok,NodeResults} | NodeResult |
565ctpm_ms(Nodes,Mod,Func,Arity,MSname) -&gt; {ok,NodeResults} |
568<p>NodeResults = [{Node,NodeResult}]
569NodeResult = ok | {error,Reason}</p>
570<p>Removes a named match-spec from the meta traced function. Note that it
571never is a fault to remove a match spec. Not even from a function
572which is non existent.</p>
573<p>When calling several nodes, the nodes are called in parallel.</p>
574<p>ctpm(Mod,Func,Arity) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
575ctpm(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}</p>
577<p>NodeResults = [{Node,NodeResult}]
578NodeResult = ok | {error,Reason}</p>
579<p>Removes the meta trace pattern for the function, means stops
580generating output for this function. The public loop data structure
581may be cleared by the previously entered RemoveFunc.</p>
582<p>When calling several nodes, the nodes are called in parallel.</p>
583<p>tpm_localnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
584tpm_localnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
586<p>NodeResults = [{Node,NodeResult}]
587NodeResult = {R1,R2}
588R1 = R2 = {ok,0} | {ok,1} | {error,Reason}</p>
589<p>Quick version for setting meta-trace patterns on erlang:register/2. It
590uses a default CallFunc and ReturnFunc in the meta-tracer server. The
591main purpose of this function is to create ti-log entries for
592associations between pids and registered name aliases. The
593implementation uses return_trace to see if the registration was
594successful or not, before actually making the ti-log alias entry.
595Further the implementation also meta traces the BIF unregister/1.</p>
596<p>If both N1 and N2 is 1, function call was successful. N1 and N2
597represent setting meta trace pattern on register/2 and unregister/1.</p>
598<p>ctpm_localnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
599ctpm_localnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
601<p>NodeResults = [{Node,NodeResult}]
602NodeResult = {R1,R2}
603R1 = R2 = ok | {error,Reason}</p>
604<p>Function for removing previously set patters by tpm_localnames/0. The
605two results R1 and R2 represents that meta pattern is removed from
606both register/2 and unregister/1.</p>
607<p>tpm_globalnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
608tpm_globalnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
610<p>NodeResults = [{Node,NodeResult}]
611NodeResult = {R1,R2}
612R1 = R2 = {ok,0} | {ok,1} | {error,Reason}</p>
613<p>Quick version for setting meta-trace patterns capable of learning the
614association of a pid with a globally registered name (registered using
615global:register_name). The implementation meta-traces on
616global:handle_call({register,&#8217;_&#8217;,&#8217;_&#8217;,&#8217;_&#8217;},&#8217;_&#8217;,&#8217;_&#8217;) and
617global:delete_global_name/2. The N1 and N2 represents the success of
618the two sub-tmp calls.</p>
619<p>ctpm_globalnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
620ctpm_globalnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
622<p>NodeResults = [{Node,NodeResult}]
623NodeResult = {R1,R2} | {error,Reason}
624R1 = R2 = ok | {error,Reason}</p>
625<p>Function for removing previously set meta patters by
626tpm_globalnames/0,1. The two results R1 and R2 represents that meta
627pattern are removed from both global:handle_call/3 and
629<p>ctp_all() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
630ctp_all(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
632<p>NodeResults = [{Node,NodeResult}]
633NodeResult = ok | {error,Reason}</p>
634<p>Clears all, both global and local trace patterns. Does not clear meta
635trace patterns. Equivalent to a call to ctp/3,4 and to ctpl/3,4 with
636wildcards &#8216;_&#8217; for all modules, functions and arities.</p>
637<p>suspend(SReason) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
638suspend(Nodes,SReason) -&gt; {ok,NodeResults} | {error,Reason}</p>
640<p>SReason = term()
641NodeResults = [{Node,NodeResult}]
642NodeResult = ok | {error,Reason}</p>
643<p>Suspends the runtime components. SReason will become the suspend-
644reason replied in for instance a get_status/0,1 call. A runtime
645component that becomes suspended removes all trace flags and all meta
646trace patterns. In that way trace output is no longer generated. The
647task of reactivating a suspended runtime component is outside the
648scoop of inviso. It can for instance be implemented by a higher layer
649trace-tool &#8220;remembering&#8221; all trace flags and meta patterns set.</p>
650<p>cancel_suspension() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
651cancel_suspend(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
653<p>NodeResults = [{Node,NodeResult}]
654NodeResult = ok | {error,Reason}</p>
655<p>Makes the runtime components running again (as opposite to suspended).
656Since reactivating previous trace flags and meta trace patterns is
657outside the scoop of inviso, cancelling suspension is simply making it
658possible to set trace flags and meta trace patterns again.</p>
659<p>get_status() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
660get_status(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
662<p>NodeResults = [{Node,NodeResult}]
663NodeResult = {ok,{State,Status}} | {error,Reason}
664State = new | idle | tracing
665Status = running | {suspended,SReason}
666SReason = term()</p>
667<p>Finds out the state and status of a runtime component. A runtime
668component is in state new before it has been initiated to do any
669tracing the first time. There are clear-functions which can make a
670runtime component become new again without having to restart. A
671runtime component becomes idle after tracing is stopped.</p>
672<p>get_tracerdata() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
673get_tracerdata(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
675<p>NodeResults = [{Node,NodeResult}]
676NodeResult = {ok,NResult} | {error,Reason}
677NResult = TracerData | no_tracerdata</p>
678<p>Returns the current tracerdata of a runtime component. A runtime
679component in state new can not have tracerdata. An idle runtime
680component does have tracerdata, the last active tracerdata. TracerData
681will be a term as specified to init_tracing when tracing was initiated
682for the runtime component.</p>
683<p>list_logs() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
684list_logs(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
685list_logs(NodeTracerData) -&gt; {ok,NodeResults} | {error,Reason}
686list_logs(TracerData) -&gt; {ok,NodeResults} | NodeResult |
689<p>TracerData &#8211; see init_tracing/1,2
690NodeResults = [{Node,NodeResult}]
691NodeResult = {ok,FileList} | {ok,no_log} | {error,Reason}
692?FileList = [FileType]
693??FileType = {trace_log,Dir,Files} | {ti_log,Dir,Files}
694??Files = [FileNameWithOutPath]</p>
695<p>Returns the actually existing log files associated with TracerData. If
696a tracerdata is not specified, current tracerdata is used for that
697particular runtime component. Files will be a list of one or more
698files should it be a wrap-set. Otherwise the it is a list of only one
700<p>This function is useful to learn the name and path of all files
701belonging to a trace. This information can later be used to move those
702files for merging. Note that since it is possible to ask on other
703tracerdata than the current, it is possible to learn filenames of
704previously done traces, under the circumstances that they have not
705been removed.</p>
706<p>fetch_log(LogSpecList,DestDir,Prefix) -&gt; {ok,NodeResults} |
707{error,not_distributed} | {error,Reason}
708fetch_log(DestDir,Prefix) -&gt; {ok,NodeResults} |
709{error,not_distributed} | {error,Reason}</p>
711<p>DestDir = string()
712Prefix = string()
713LogSpecList = [LogSpec]
714?LogSpec = {Node,FileSpecList} | Node | {Node,TracerData}
715TracerData = see init_tracing/1,/2
716FileSpecList = [{trace_log,Dir,FileList},{ti_log,Dir,FileList}] |
718?FileList = [RemoteFileName]
719NodeResult = {Conclusion,ResultFileSpec} | no_log | {error,NReason}
720?NReason = own_node | Reason
721?Conclusion = complete | incomplete
722?ResultFileSpec = [{trace_log,FileResults},{ti_log,FileResults}]
723??FileResults = [FileResult]
724??? FileResult = {ok,FileName} | {error,FReason}
725????FReason = {file_open,{posix(),FileName}} |
726{file_open,{posix(),RemoteFileName}} |
727{file_open,{posix(),[DestDir,Prefix,RemoteFileName]}} |
728{file_write,{posix(),FileName}} | {truncated,FileName} |
730?????posix() = atom()</p>
731<p>Copies log files over distributed erlang to the control component
732node. This function can only be used in a distributed system.</p>
733<p>The resulting transferred files will have the prefix Prefix and will
734be located in DestDir. The source files can either be pointed out
735using a FileListSpec or tracerdata. If no files are explicitly
736specified, current tracerdata for that node will be used. Note that if
737source files have the same name (on several nodes) they will overwrite
738each other at DestDir.</p>
739<p>delete_log(Nodes,TracerData) -&gt; {ok,NodeResults} | {error,Reason}
740delete_log(NodeSpecList) -&gt; {ok,NodeResults} | {error,Reason}
741delete_log(Spec) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
742delete_log(TracerData) -&gt; {ok,NodeResults} | NodeResult |
744delete_log() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
746<p>Nodes = [Node]
747NodeSpecList = [{Node,Spec}]
748?Spec = [AbsPathFileName] | LogSpecs
749??LogSpecs = [LogSpec]
750???LogSpec = {trace_log,Dir,[FileNameWithoutPath]} |
752TracerData &#8211; see init_tracing/1,/2
753NodeResults = [{Node,NodeResult}]
754NodeResult = {ok,no_log} | {ok,LogInfos} | {ok,FileInfos}
755?LogInfos = [LogInfo]
756??LogInfo = {trace_log,FileInfos} | {ti_log,FileInfos}
757?FileInfos = [FileInfo]
758??FileInfo = {ok,FileName} | {error,Reason}</p>
759<p>Deletes listed files or files corresponding to tracerdata. If no
760tracerdata or list of files are specified in the call, current
761tracerdata at the runtime components will be used to identify files to
762delete. All filenames shall be strings.</p>
763<p>FileName can either be an absolute path or just a filename depending
764on if AbsPathFileName or a LogSpec was used to identify the file.</p>
765<p>subscribe() -&gt; ok | {error,Reason}
766subscribe(Pid) -&gt; ok | {error,Reason}</p>
768<p>Pid = pid()</p>
769<p>Adds Pid or self() if using subscribe/0 to the inviso-event sending
770list. Note that it is possible to add a pid several times and that the
771Pid then will receive multiple copies of inviso-event messages.</p>
772<p>All events will be sent to all subscribers in the event sending list.</p>
773<div class="highlight-erlang"><div class="highlight"><pre><span class="nv">Event</span> <span class="o">=</span> <span class="p">{</span><span class="n">inviso_event</span><span class="p">,</span><span class="nv">ControllerPid</span><span class="p">,</span><span class="nn">erlang</span><span class="p">:</span><span class="n">localtime</span><span class="p">(),</span><span class="nv">Msg</span><span class="p">}</span>
774  <span class="nv">Msg</span> <span class="o">=</span> <span class="p">{</span><span class="n">connected</span><span class="p">,</span> <span class="nv">Node</span><span class="p">,</span> <span class="p">{</span><span class="nv">RTtag</span><span class="p">,</span> <span class="p">{</span><span class="nv">State</span><span class="p">,</span><span class="nv">Status</span><span class="p">}}}</span>
775      <span class="p">|</span> <span class="p">{</span><span class="n">disconnected</span><span class="p">,</span> <span class="nv">Node</span><span class="p">,</span> <span class="nv">NA</span><span class="p">}</span>
776      <span class="p">|</span> <span class="p">{</span><span class="n">state_change</span><span class="p">,</span><span class="nv">Node</span><span class="p">,{</span><span class="nv">State</span><span class="p">,</span><span class="nv">Status</span><span class="p">}}</span>
777      <span class="p">|</span> <span class="p">{</span><span class="n">port_down</span><span class="p">,</span><span class="nv">Node</span><span class="p">,</span><span class="nv">Reason</span><span class="p">}</span>
778    <span class="nv">Node</span> <span class="o">=</span> <span class="nb">node</span><span class="p">()</span> <span class="p">|</span> <span class="n">local_runtime</span>
781<p>Subscribing to inviso-event may be necessary for a higher layer trace-
782tool using inviso to follow the runtime components. local_runtime will
783be used for a runtime component running in a non-distributed
785<p>unsubscribe() -&gt; ok
786unsubscribe(Pid) -&gt; ok</p>
787<p>Removes Pid (once) from the subscription list.</p>
788<p>inviso 0.6
789Copyright ? 1991-2009 <a class="reference external" href="">Ericsson AB</a></p>
795          </div>
796        </div>
797      </div>
798      <div class="sphinxsidebar">
799        <div class="sphinxsidebarwrapper">
800            <h3><a href="../../../../index.html">Table Of Contents</a></h3>
801            <ul>
802<li><a class="reference external" href="">Lib - Inviso-0.6 - Doc - Html - Inviso</a><ul>
803<li><a class="reference external" href="#inviso">inviso</a><ul>
804<li><a class="reference external" href="#module">MODULE</a></li>
805<li><a class="reference external" href="#module-summary">MODULE SUMMARY</a></li>
806<li><a class="reference external" href="#description">DESCRIPTION</a></li>
807<li><a class="reference external" href="#exports">EXPORTS</a></li>
814            <h3>This Page</h3>
815            <ul class="this-page-menu">
816              <li><a href="../../../../_sources/lib/inviso-0.6/doc/html/inviso.txt"
817                     rel="nofollow">Show Source</a></li>
818            </ul>
819          <div id="searchbox" style="display: none">
820            <h3>Quick search</h3>
821              <form class="search" action="../../../../search.html" method="get">
822                <input type="text" name="q" size="18" />
823                <input type="submit" value="Go" />
824                <input type="hidden" name="check_keywords" value="yes" />
825                <input type="hidden" name="area" value="default" />
826              </form>
827              <p class="searchtip" style="font-size: 90%">
828              Enter search terms or a module, class or function name.
829              </p>
830          </div>
831          <script type="text/javascript">$('#searchbox').show(0);</script>
832        </div>
833      </div>
834      <div class="clearer"></div>
835    </div>
836    <div class="related">
837      <h3>Navigation</h3>
838      <ul>
839        <li class="right" style="margin-right: 10px">
840          <a href="../../../../genindex.html" title="General Index"
841             >index</a></li>
842        <li><a href="../../../../index.html">Erlang/OTP vR13B02 documentation</a> &raquo;</li> 
843      </ul>
844    </div>
845    <div class="footer">
846        &copy; Copyright 1999-2009 Ericsson AB.
847      Created using <a href="">Sphinx</a> 1.0.
848    </div>
849  </body>