inviso.erl

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

%% ``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$
%%
%% Author: Ann-Marie L鰂, [e-mail]
%%         Lennart 謍man, [e-mail]
%%
%% Description: API module for the inviso system.
%% Inviso consists of a control component and possibly one or more runtime
%% components. This module is simply the API to the inviso system. All normal
%% calls goes through the control component.
%% ------------------------------------------------------------------------------

-module(inviso).

%% ------------------------------------------------------------------------------
%% Exported API functions.
%% ------------------------------------------------------------------------------

-export([start/0, start/1,
	 add_node/1, add_node/2, add_node_if_ref/1, add_node_if_ref/2,
	 add_nodes/2, add_nodes/3, add_nodes_if_ref/2, add_nodes_if_ref/3,
	 change_options/1, change_options/2,
	 init_tracing/1, init_tracing/2, 
	 stop_tracing/0, stop_tracing/1, 
	 clear/0, clear/1, clear/2,
	 stop/0, stop_nodes/0, stop_nodes/1, stop_all/0,
	 tp/1,tp/2,tp/4,tp/5,tp/6,
	 tpl/1,tpl/2,tpl/4,tpl/5,tpl/6,
	 tpm_localnames/0,tpm_localnames/1,tpm_globalnames/0,tpm_globalnames/1,
	 init_tpm/4,init_tpm/5,init_tpm/7,init_tpm/8,
	 tpm/4,tpm/5,tpm/6,tpm/8,tpm/9,
	 tpm_tracer/4,tpm_tracer/5,tpm_tracer/6,tpm_tracer/8,tpm_tracer/9,
	 tpm_ms/5,tpm_ms/6,
	 tpm_ms_tracer/5,tpm_ms_tracer/6,
	 ctpm_ms/4,ctpm_ms/5,ctpm/3,ctpm/4,
	 ctpm_localnames/0,ctpm_localnames/1,ctpm_globalnames/0,ctpm_globalnames/1,
	 ctp/1,ctp/2,ctp/3,ctp/4,
	 ctpl/1,ctpl/2,ctpl/3,ctpl/4,
	 tf/1, tf/2, tf/3,
	 ctf/1, ctf/2, ctf/3,
	 ctp_all/0, ctp_all/1, ctf_all/0, ctf_all/1,
	 suspend/1, suspend/2,
	 cancel_suspension/0, cancel_suspension/1,
	 get_status/0, get_status/1,
	 get_tracerdata/0, get_tracerdata/1,
	 list_logs/0, list_logs/1,
	 fetch_log/2, fetch_log/3, fetch_log/4,
	 delete_log/0, delete_log/1, delete_log/2,
	 subscribe/0, subscribe/1, 
	 unsubscribe/0, unsubscribe/1]).

%% debuging inviso
-export([state/0, state/1]).

%% ------------------------------------------------------------------------------
%% Macros used in this module.
%% ------------------------------------------------------------------------------

-define(CONTROLLER,inviso_c).
%% ------------------------------------------------------------------------------


%% =============================================================================
%% CONTROL COMPONENT API FUNCTIONS.
%% =============================================================================

%% start()={ok,pid()}|{error,Reason}
%% start(Options)={ok,pid()}|{error,Reason} 
%%   Options=[Option,...], the options will be default options to runtime components
%%     later started. See add_node about available options.
%%     There are also options consumed by the control component:
%%       Option={subscribe,pid()}
%%
%% Starts a control component process on the local node. A control component must
%% be started before runtime components can be started manually.
start() ->
    gen_server:start({local,?CONTROLLER},?CONTROLLER,{self(),[]},[]).

start(Options) ->
    gen_server:start({local,?CONTROLLER},?CONTROLLER,{self(),Options},[]).
%% -----------------------------------------------------------------------------

%% add_node(Reference)=NodeResult|{error, Reason}
%% add_node(Reference,Options)=NodeResult|{error, Reason}
%%   Reference=PreviousReference = term(),
%%   Options=[Option,...],
%%   Option={dependency,Dep}
%%     Dep=integer()|'infinity'; The timeout before the runtime component will
%%       terminate if abandoned by this control component.
%%   Option={overload,Overload}; controls how and how often overload checks shall
%%       be performed. Instead of specifying a tuple, the atom 'overload' can be
%%       specified to state no loadcheck. The result will actually be the same
%%       if 'infinity' is used as intervall. It is sometimes necessary to
%%       initialize the overlaod check. This can be done with InitMFA. The
%%       loadchecker must then also be removed by using a RemoveMFA.
%%     Overload=Iterval (int() in milliseconds) |
%%         {LoadMF,Interval}|{LoadMF,Interval,InitMFA,RemoveMFA}
%%           LoadMF={Mod,Func}
%%           InitMFA,RemoveMFA={Mod,Func,ArgList}|void
%%           If just Interval is used, it means using a default overload check.
%%   NodeResult={ok,NAns}|{error,Reason} 
%%   NAns=new|{adopted,State,Status,PreviousReference}|already_added
%%   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.
add_node(Reference) ->
    gen_server:call(?CONTROLLER,{add_nodes,[node()],[],Reference,any_ref}).

add_node(Reference,Options) when list(Options) ->
    gen_server:call(?CONTROLLER,{add_nodes,[node()],Options,Reference,any_ref}).
%% -----------------------------------------------------------------------------

%% add_node(Reference)=NodeResult|{error,{wrong_reference,OtherRef}}|{error,Reason}
%% add_node(Reference,Options)=NodeResult|{error,{wrong_reference,OtherRef}}|
%%   {error,Reason}
%%
%% As add_node/1,/2 but will only connect to an already existing runtime component
%% if its reference is the same as the one given as argument.
add_node_if_ref(Reference) ->
    gen_server:call(?CONTROLLER,{add_nodes,[node()],[],Reference,if_ref}).

add_node_if_ref(Reference,Options) when list(Options) ->
    gen_server:call(?CONTROLLER,{add_nodes,[node()],Options,Reference,if_ref}).
%% -----------------------------------------------------------------------------

%% add_nodes(Nodes,Reference)={ok,NodeResults}|{error,Reason}
%% add_nodes(Nodes,Reference,Options)={ok,NodeResults}|{error,Reason}
%%   Nodes=[Node,...], 
%%   NodeResults=[{Node,NodeResult},...]
%%
%% As add_node/1,/2 but for the nodes specified in Nodes.
%% It is possible but not intended to use this function in a non-distributed
%% system. By speicifying node() as the node where the runtime component shall
%% be started. The return value will then follow the rules of non distributed
%% returnvalues and not have a node indicator.
add_nodes(Nodes,Reference) when list(Nodes) ->
    gen_server:call(?CONTROLLER,{add_nodes,Nodes,[],Reference,any_ref}).

add_nodes(Nodes,Reference,Options) when list(Nodes),list(Options) ->
    gen_server:call(?CONTROLLER,{add_nodes,Nodes,Options,Reference,any_ref}).
%% -----------------------------------------------------------------------------

%% add_nodes_if_ref(Nodes,Reference)={ok,NodeResults}|{error,Reason}
%% add_nodes_if_ref(Nodes,Reference,Options)={ok,NodeResults}|{error,Reason}
%%
%% As add_nodes/2,/3 but will only connect to an already existing runtime component
%% if its reference is the same as the one given as argument.
add_nodes_if_ref(Nodes,Reference) when list(Nodes) ->
    gen_server:call(?CONTROLLER,{add_nodes,Nodes,[],Reference,if_ref}).

add_nodes_if_ref(Nodes,Reference,Options) when list(Nodes),list(Options) ->
    gen_server:call(?CONTROLLER,{add_nodes,Nodes,Options,Reference,if_ref}).
%% -----------------------------------------------------------------------------

%% change_options(Options)={ok,NodeResults}|NodeResult|{error,Reason}
%% change_options(Nodes,Options)={ok,NodeResults}|{error,Reason}
%%   Nodes=[Node,...], 
%%   Options= see add_node and add_nodes on available options.
%%
%% Change options on all or specified Nodes. This may result in for instance
%% reinitialization of overloadcheck.
change_options(Options) when list(Options) ->
    gen_server:call(?CONTROLLER,{change_options,all,Options}).
change_options(Nodes,Options) when list(Nodes),list(Options)  ->
    gen_server:call(?CONTROLLER,{change_options,Nodes,Options}).
%% -----------------------------------------------------------------------------

%% init_tracing(TracerData)={ok,[{Node,NodeResult}]} | NodeResult | {error,Reason}
%% init_tracing(TracerList)={ok,[{Node,NodeResult}]} | {error,Reason}
%% init_tracing(Nodes,TracerData)={ok,[{Node,NodeResult}]}|{error,Reason}
%%   TracerData = [{trace,LogTD} [,{ti,TiTD}]}] | LogTD
%%   LogTD      = {HandlerFun,Data} | collector | {relayer,pid()} |  
%%                {relayer,CollectingNode} | {ip,IPPortParameters} |
%%                {file,FilePortParameters}
%%   TiTD       = {file,FileName} | {file,FileName,TiMFA}
%%   TiMFA      = {Module,Function,ArgumentList} initiating a private loopdata
%%                inside the meta-tracer.
%%   TracerList = [{Node,TracerData}],
%%   IPPortParameters = Portno | {Portno, Qsiz}
%%   Qsiz = 
%%   FilePortParameters = {Filename, wrap, Tail, {time, WrapTime}, WrapCnt} |
%%                        {FileName, wrap, Tail, WrapSize, WrapCnt} |
%%                        {FileName, wrap, Tail, WrapSize} |
%%                        {FileName, wrap, Tail} | FileName
%%                          Tail =/= ""
%%   HandlerFun is a function taking 2 arguments.
%%   Nodes = [node()], 
%%   CollectingNode = pid() | node(),
%%   NodeResult = {ok,LogResults} | {error, NReason} 
%%     LogResults=[LogResult,...]
%%       LogResult={trace_log,LogRes} | {ti_log,LogRes}
%%         LogRes=ok|{error,Reason}
%%
%% Starts tracing on the nodes specified. If just providing a TracerData tracing
%% will be initiated on all our nodes. If it is the non distributed case, that
%% means only on the local non distributed node.
%%
%% {HandlerFun,Data}
%%   Will use the runtime components own process as tracer and handle all
%%   incomming trace message using HandlerFun.
%% {relayer,CollectingNode}
%%   The runtime component addressed will act tracer and relay all incomming trace
%%   messages to Node or Pid, if CollectingNode is not a traced node connected 
%%   to the controll component, the init_tracing call will return an error.
%%   Note that {relayer, Node} only is syntactical sugar for
%%   {relayer, rpc:call(Node,erlang,whereis,[inviso_rt])}
%% collector
%%   The runtime component is used as tracer or collector of relayed 
%%   trace messages using the default handler writing them to io.
%% ip | file - will open a trace-port on Node using PortParameters
init_tracing(TracerDataList) ->
    gen_server:call(?CONTROLLER,{init_tracing,TracerDataList}).

init_tracing(Nodes,TracerData) when list(Nodes) ->
    gen_server:call(?CONTROLLER,{init_tracing,Nodes,TracerData}).
%% -----------------------------------------------------------------------------

%% stop_tracing(Nodes)={ok,NodeResults}|{error,Reason}
%% stop_tracing()={ok,NodeResults}|NodeResult}
%%   Nodes=[Node,...], 
%%   NodeResults=[{Node,NodeResult},...]
%%   NodeResult={ok,State}|{error,Reason}
%%     State=new|idle
%% Stops tracing on all or specified Nodes. Flushes trace buffert, 
%% closes trace port and removes all trace flags and meta-patterns.
%% The nodes are called in parallel.
stop_tracing() ->
    gen_server:call(?CONTROLLER,{stop_tracing,all}).

stop_tracing(Nodes) when is_list(Nodes) ->
    gen_server:call(?CONTROLLER,{stop_tracing,Nodes}).
%% -----------------------------------------------------------------------------

%% clear()={ok,NodeResults}|NodeResult
%% clear(Nodes,Options)={ok,NodeResults}|{error,Reason}
%% clear(Options)={ok,NodeResults}|NodeResult|{error,Reason}
%%   Nodes=[Node,...], 
%%   Options=[Option,...],
%%   Option=keep_trace_patterns|keep_log_files
%%   NodeResults=[{Node,NodeResult},...]