inviso.sgml

来自「OTP是开放电信平台的简称」· SGML 代码 · 共 779 行 · 第 1/4 页

<!doctype erlref PUBLIC "-//Stork//DTD erlref//EN">
<!-- 
 ``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 via the world wide web 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 Utvecklings AB.
 Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
 AB. All Rights Reserved.''
 
     $Id$
-->
<erlref>
  <header>
    <title>inviso</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>inviso</module>
  <modulesummary>Main API Module to the Inviso Tracer</modulesummary>
  <description>
    <p>With the <c>inviso</c> API runtime components can be started and tracing managed across a network of distributed Erlang nodes, using a control component also started with <c>inviso</c> API functions.</p>

    <p>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 <c>NodeResult</c> refers to return values from a single Erlang node, and will therefore be the return in the non-distributed environment.</p>
  </description>

  <funcs>
    <func>
      <name>start() -> {ok,pid()} | {error,Reason}</name>
      <name>start(Options) -> {ok,pid()} | {error,Reason}</name>
      <fsummary>Start a control component at the local node</fsummary>
      <type>
	<v>Options = [Option]</v>
      </type>
      <desc>
	<p><c>Options</c> may contain both options which will be default options to a runtime component when started, and options to the control component. See <seealso marker="#add_nodes/3">add_nodes/3</seealso> for details on runtime component options. The control component recognizes the following options:</p>
	<taglist>
	  <tag><c>{subscribe,Pid}</c></tag>
	  <item>
	    <p>Making the process <c>Pid</c> receive Inviso events from the control component.</p>

	    <p>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 <c>inviso</c> API.</p>
	  </item>
	</taglist>
      </desc>
    </func>

    <func>
      <name>stop() -> shutdown</name>
      <fsummary>Stop the control component</fsummary>
      <desc>
	<p>Stops the control component. Runtime components are left as is. They will behave according to their dependency values.</p>
      </desc>
    </func>

    <func>
      <name>add_node(RTtag) -> NodeResult | {error,Reason}</name>
      <name>add_node(RTtag,Options) -> NodeResult | {error,Reason}</name>
      <fsummary>Starts or adopts a runtime component at the local node</fsummary>
      <type>
	<v>RTtag = PreviousRTtag = term()</v>
	<v>Options = [Option]</v>
	<v>&nbsp;Option -- see below</v>
	<v>&nbsp;Option = {dependency,Dep}</v>
	<v>&nbsp;&nbsp;Dep = int() | infinity</v>
	<d>The timeout, in milliseconds, before the runtime component will terminate if abandoned by <em>this</em> control component.</d>
	<v>&nbsp;Option = {overload,Overload} | overload</v>
	<d>Controls how and how often overload checks shall be performed. Just <c>overload</c> specifies that no loadcheck shall be performed.</d>
	<v>&nbsp;&nbsp;Overload = Interval | {LoadMF,Interval,InitMFA,RemoveMFA}</v>
	<v>&nbsp;&nbsp;&nbsp;LoadMF = {Mod,Func} | function()/1</v>
	<v>&nbsp;&nbsp;&nbsp;Interval = int() | infinity</v>
	<d>Interval is the time in milliseconds between overload checks.</d>
	<v>&nbsp;&nbsp;&nbsp;InitMFA = RemoveMFA = {Mod,Func,ArgList} | void</v>
	<d>When starting up the runtime component or when changing options (see <c>change_options/2</c>) the overload mechanism is initialized with a call to the <c>InitMFA</c> function. It shall return <c>LoadCheckData</c>. Every time a load check is performed, <c>LoadMF</c> is called with <c>LoadCheckData</c> as its only argument. <c>LoadMF</c> shall return <c>ok</c> or <c>{suspend,Reason}</c>. When the runtime component is stopped or made to change options involving changing overload-check, the <c>RemoveMFA</c> function is called. Its return value is discarded.</d>
	<v>NodeResult = {ok,NAns} | {error,Reason}</v>
	<v>&nbsp;NAns = new | {adopted,State,Status,PreviousRTtag} | already_added</v>
	<v>&nbsp;&nbsp;State = new | tracing | idle</v>
	<v>&nbsp;&nbsp;Status = running | {suspended,SReason}</v>
      </type>
      <desc>
	<p>Starts or tries to connect to an existing runtime component at the local node, regardless if the system is distributed or not. <c>Options</c> will override any default options specified at start-up of the control component.</p>

	<p>The <c>PreviousRTtag</c> 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.</p>
      </desc>
    </func>

    <func>
      <name>add_node_if_ref(RTtag) -> NodeResult | {error,{wrong_reference,OtherTag}} | {error,Reason}</name>
      <name>add_node_if_ref(RTtag,Options) -> NodeResult | {error,{wrong_reference,OtherRef}} | {error,Reason}</name>
      <fsummary>Start or adopt a runtime component at the local node, provided it has a certain rttag</fsummary>
      <type>
	<v>OtherRef = term()</v>
	<d>rttag of the running incarnation</d>
      </type>
      <desc>
	<p>As <seealso marker="#add_node/1">add_node/1,2</seealso> but will only adopt the runtime component if its rttag is <c>RTtag</c>.</p>
      </desc>
    </func>

    <func>
	<name>add_nodes(Nodes,RTtag) -> {ok,NodeResults} | {error,Reason}</name>
	<name>add_nodes(Nodes,RTtag,Options) -> {ok,NodeResults} | {error,Reason}</name>
      <fsummary>Start or adopt runtime components at some nodes</fsummary>
      <type>
	<v>Nodes = [Node]</v>
	<v>NodeResults = [{Node,NodeResult}]</v>
      </type>
      <desc>
	<p>As <seealso marker="#add_node/1">add_node/1,2</seealso> but for a distributed environment.</p>
      </desc>
    </func>

    <func>
      <name>add_nodes_if_ref(Nodes,RTtag) -> NodeResult | {error,Reason}</name>
      <name>add_nodes_if_ref(Nodes,RTtag,Options) -> NodeResult | {error,Reason}</name>
      <fsummary>Start or adopt runtime components at some nodes, provided they have a certain rttag</fsummary>
      <type>
	<v>Nodes = [Node]</v>
	<v>NodeResults = [{Node,NodeResult}]</v>
      </type>
      <desc>
	<p>As <seealso marker="#add_node_if_ref/1">add_node_if_ref/1,2</seealso> but for a distributed environment.</p>
      </desc>
    </func>

    <func>
      <name>stop_nodes() -> {ok,NodeResults} | NodeResult</name>
      <name>stop_nodes(Nodes) -> {ok,NodeResults} | {error,Reason}</name>
      <fsummary>Stop runtime components</fsummary>
      <type>
	<v>NodeResults = [{Node,NodeResult}]</v>
	<v>NodeResult = ok | {error,Reason}</v>
      </type>
      <desc>
	<p>Stops runtime component on <c>Nodes</c>. <c>stop_nodes/0</c> 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.</p>
      </desc>
    </func>

    <func>
      <name>stop_all() = {ok,NodeResults} | NodeResult</name>
      <fsummary>Stop both control and runtime components</fsummary>
      <type>
	<v>NodeResults = [{Node,NodeResult}]</v>
	<v>NodeResult = ok | {error,Reason}</v>
      </type>
      <desc>
	<p>A combination of <seealso marker="#stop/0">stop/0</seealso> and <seealso marker="#stop_nodes/0">stop_nodes/0</seealso>.</p>
      </desc>
    </func>

    <func>
      <name>change_options(Options) -> NodeResult | {ok,NodeResults} | {error,Reason}</name>
      <name>change_options(Nodes,Options) -> {ok,NodeResults} | {error,Reason}</name>
      <fsummary>Change options for runtime components</fsummary>
      <type>
	<v>Nodes = [Node]</v>
	<v>NodeResults = [{Node,NodeResult}]</v>
	<v>NodeResult = ok | {error,Reason}</v>
      </type>
      <desc>
	<p>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 <seealso marker="#add_node/1">add_node/1</seealso> for details on <c>Options</c>.</p>
      </desc>
    </func>

    <func>
      <name>init_tracing(TracerData) -> {ok,NodeResults} | NodeResult | {error,Reason}</name>
      <name>init_tracing(TracerList) -> {ok,NodeResults} | {error,Reason}</name>
      <name>init_tracing(Nodes,TracerData) -> {ok,NodeResults} | {error,Reason}</name>
      <fsummary>Initiate tracing</fsummary>
      <type>
	<v>TracerData = [{trace,LogTD} [,{ti,TiTD}] }] | LogTD</v>
	<v>LogTD = {HandlerFun,Data1} | collector | {relayer,CollectingNode} | {ip,IPPortParameters} | {file,FilePortParameters}</v>
	<v>TiTD = {file,FileName} | {file,FileName,TiSpec} | {relay,Node}</v>
	<v>&nbsp;TiSpec = {InitMFA,RemoveMF,CleanMF}</v>
	<v>&nbsp;&nbsp;InitMFA = {Mi,Fi,Argsi}</v>
	<v>&nbsp;&nbsp;RemoveMF = {Mr,Fr} | void</v>
	<v>&nbsp;&nbsp;CleanMF = {Mc,Fc}</v>
	<v>&nbsp;&nbsp;Mi = Fi = Mr = Fr = Mc = Fd = atom()</v>
	<v>&nbsp;&nbsp;Argsi = [term()]</v>
	<v>TracerList = [{Node,TracerData}]</v>
	<v>IPPortParameters = Portno | {Portno,Qsize}</v>
	<v>&nbsp;Portno = tcp_portno()</v>
	<v>&nbsp;Qsize = int()</v>
	<v>FilePortParameters = 
	  {Filename,wrap,Tail,{time,WrapTime},WrapCnt} |
	  {FileName,wrap,Tail,WrapSize,WrapCnt} |