inviso_tool.erl

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

% ``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$
%%
%% Description:
%% The inviso_tool implementation. A tool that uses inviso.
%%
%% Authors:
%% Lennart 謍man, [e-mail]
%% -----------------------------------------------------------------------------

-module(inviso_tool).


%% This is the inviso tool, which is a tool using the inviso trace application.
%% It is developed to make tracing using trace cases possible in an environment
%% of distributed Erlang nodes.
%% A current restriction is that the Erlang nodes are supposed to have the same
%% code. This since inviso tool can at this point not handle subsets of nodes.
%% Instead all participating Erlang nodes are treated the same.
%%
%% The main functionality of the inviso tool are:
%%
%% (1) Handles start and stop of tracing at participating nodes.
%% (2) Interprets trace-case files at a distributed network level.
%%     (The inviso runtime component is responsible for interpreting
%%      trace cases at a local level, if run in an autostart).
%% (3) Keeps a command history log from which:
%%     (a) Sequences easily can be repeated.
%%     (b) Autostart configuration files can be created (understood by the
%%         default inviso autostart mechanism).
%% (4) Performs reactivation in case tracing is suspended (manually or by
%%     an overload mechanism).
%% (5) Can reconnect crashed nodes and by using the history bringing them
%%     up to speed.

%% Distributed Erlang
%% ------------------
%% Inviso is built to run in a distributed environment.
%% The inviso tool can also be used in a non distributed environment.

%% Short description
%% -----------------
%% Start-up of the inviso tool
%% During the start-up of the tool, the tool starts runtime components at
%% all participating nodes. A runtime component can already be running at
%% a particular node and will then simply be adopted.
%%
%% Session
%% A session is said to start when tracing is initiated, and ends when
%% made to stop by the user. When a session is stopped, tracing is stopped
%% at all participating nodes. Note that participating nodes may come and
%% go though the time-frame of a session. That means that if a node is
%% reconnected it may resume its tracing in the current session through
%% a 'restart_session'. A runtime component that is already tracing at the
%% time start-session will simply be part of the session without its
%% ingoing tracing being changed.
%%
%% Reactivation
%% A node that is suspended can be reactivated to resume tracing. Note that
%% tracing has in this situation never been stopped at the node in question.
%% The inviso tool resumes the node and applies the history to it.
%%
%% Reconnect
%% A node that is "down" from the inviso tool's perspective can be
%% reconnected. During reconnection the tool restarts the runtime component
%% at that node but does not (re)initiate tracing. The latter is called
%% restart_session and must be done explicitly, unless the node in question
%% is in fact already tracing. If the node is already tracing (due to an autostart
%% for instance), it automatically becomes part of the ongoing session (if
%% there is an ongoing session).
%%
%% Restart Session
%% A node that has been down and has been reconnected can be made to
%% initialize and resume its tracing. This is done by starting the session
%% at the node in question and redoing the current history.

%% Trace files within a session
%% Since it is possible to init-tracing (from an inviso perspective) several
%% times within the same session, a session may leave several trace log files
%% behind. This must be resolved by the tracer data generator function
%% (user supplied) by marking filenames in a chronological order but still
%% making them possible to identify as part of the same session



%% -----------------------------------------------------------------------------
%% API exports.
%% -----------------------------------------------------------------------------

-export([start/0,start/1,stop/0]).
-export([reconnect_nodes/0,reconnect_nodes/1,
	 start_session/0,start_session/1,
	 reinitiate_session/0,reinitiate_session/1,
	 restore_session/0,restore_session/1,restore_session/2,
	 stop_session/0,
	 reset_nodes/0,reset_nodes/1,
	 atc/3,sync_atc/3,sync_atc/4,
	 dtc/2,sync_dtc/2,sync_dtc/3,
	 inviso/2]).
-export([reactivate/0,reactivate/1,
	 save_history/1,
	 get_autostart_data/1,get_autostart_data/2,
	 get_activities/0,get_node_status/0,get_node_status/1]).
%% -----------------------------------------------------------------------------

%% -----------------------------------------------------------------------------
%% Debug exports.
%% -----------------------------------------------------------------------------

-export([get_loopdata/0]).
%% -----------------------------------------------------------------------------

%% -----------------------------------------------------------------------------
%% OTP exports and call backs.
%% -----------------------------------------------------------------------------

-export([init/1,handle_call/3,handle_cast/2,handle_info/2,terminate/2]).
%% -----------------------------------------------------------------------------

%% -----------------------------------------------------------------------------
%% Internal exports.
%% -----------------------------------------------------------------------------

-export([tc_executer/4,reactivator_executer/6]).
-export([std_options_generator/1]).
%% -----------------------------------------------------------------------------

%% -----------------------------------------------------------------------------
%% Constants.
%% -----------------------------------------------------------------------------

%% Defines the inviso function calls that shall be possible to do through the
%% inviso API in this tool.
-define(INVISO_CMDS,
	[{tp,5},{tp,4},{tp,1},{tpl,5},{tpl,4},{tpl,1},
	 {ctp,1},{ctp,2},{ctp,3},{ctpl,1},{ctpl,2},{ctpl,3},
	 {tf,2},{tf,1},{ctf,2},{ctf,1},{ctf_all,0},
	 {init_tpm,4},{init_tpm,7},
	 {tpm,4},{tpm,5},{tpm,8},
	 {tpm_tracer,4},{tpm_tracer,5},{init_tpm,8},
	 {tpm_ms,5},{tpm_ms_tracer,5},
	 {ctpm_ms,4},{ctpm,3},
	 {tpm_localnames,0},{ctpm_localnames,0},
	 {tpm_globalnames,0},{ctpm_globalnames,0},
	 {ctp_all,0},
	 {suspend,1},{cancel_suspension,0}]).
%% -----------------------------------------------------------------------------

%% These inviso functions shall be included in the command history log. Others
%% are not relevant to be redone during a recactivation, a restart session or
%% exported to an autostart file.
-define(INVISO_CMD_HISTORY,
	[{tp,5},{tp,4},{tp,1},{tpl,5},{tpl,4},{tpl,1},
	 {ctp,1},{ctp,2},{ctp,3},{ctpl,1},{ctpl,2},{ctpl,3},
	 {tf,2},{tf,1},{ctf,2},{ctf,1},{ctf_all,0},
	 {init_tpm,4},{init_tpm,7},
	 {tpm,4},{tpm,5},{tpm,8},
	 {tpm_tracer,4},{tpm_tracer,5},{init_tpm,8},
	 {tpm_ms,5},{tpm_ms_tracer,5},
	 {ctpm_ms,4},{ctpm,3},
	 {tpm_localnames,0},{ctpm_localnames,0},
	 {tpm_globalnames,0},{ctpm_globalnames,0},
	 {ctp_all,0}]).
%% -----------------------------------------------------------------------------

%% Default max time to wait for a trace case called synchronously to return.
-define(SYNC_TC_TIMEOUT,10000).

%% Runtime components shall terminate when the tool terminates.
-define(DEFAULT_DEPENDENCY,{dependency,0}).
%% -----------------------------------------------------------------------------

%% -----------------------------------------------------------------------------
%% Record definitions.
%% -----------------------------------------------------------------------------

%% The loopdata record.
-record(ld,{
	  dir=".",                          % Working dir of the tool.
	  nodes=down,                       % The nodesD database, defaults to non-distr.
	  c_node,                           % Location of inviso_c.
	  c_pid,                            % The inviso control component.
	  regexp_node,                      % Node for regexp expansions.
	  tc_dict,                          % Trace case definition db.
	  chl,                              % Command history log.
	  session_state=passive,            % passive | tracing
	  tdg={inviso_tool_lib,std_tdg,[]}, % Tracer data generator func.
	  tracer_data,                      % Current session nr and TDGargs.
	  reactivators=[],                  % Pids of now running reactivators.
	  tc_def_file,                      % Trace case definition file.
	  optg={?MODULE,std_options_generator,[]}, % Generates options to add_nodes/3.
	  initial_tcs=[],                   % Initial trace cases.
	  started_initial_tcs=[],           % Cases that must be stopped when stop_tracing.
	  history_dir,                      % File path for history file.
	  keep_nodes=[],                    % Nodes that shall not be cleared when stopping.
	  debug=false                       % Internal debug mode
	  }).
%% -----------------------------------------------------------------------------


%% =============================================================================
%% API
%% =============================================================================

%% start()={ok,Pid} | {error,{already_started,pid()}}
%% start(Config)
%%   Config=[{Opt,Value},...], list of tuple options.
%%     Opt=dir|nodes|c_node|regexp_node|tdg|tc_def_file|optg|initial_tcs|
%%           history_dir|keep_nodes
%% Starts the inviso_tool process. Options in Config are the same as those
%% which are kept in the #ld structure.
start() ->
    start([]).
start(Config) ->
    gen_server:start({local,?MODULE},?MODULE,Config,[]).
%% -----------------------------------------------------------------------------

%% stop()={ok,NodeResults} | NodeResult | {error,Reason}
%%   NodeResults=[{Node,NodeResult},...]
%%   NodeResult=ok | {error,Reason} | patterns_untouched
%% Stops the inviso tool and the inviso control component. Runtime components are
%% stopped by them selves depending on their dependcy of the control component.
%% All runtime components that are not marked as to be kept will have their
%% trace patterns cleared before the inviso control component is shutdown.
%% The NodeResults indicates which nodes were successfullt handled.
stop() ->
    gen_server:call(?MODULE,stop).
%% -----------------------------------------------------------------------------

%% reconnect_nodes()=NodeResult; function for the nod-distributed case.
%% reconnect_nodes(Nodes)={ok,NodesResults}
%%   NodesResults=[{Node,NodeResult},...]
%%     NodeResult={ok,{State,Status}} | {error,NReason}
%%       State=tracing | inactive
%%       Status=running | suspended
%%       NReason=unknown_node | already_connected | down
%% (Re)starts the inviso runtime components at Nodes. Depending on its state
%% (new,idle or tracing) and if the tool is running a session or not, it becomes
%% part of the tool's ongoing session. If the newly reconnected node is not
%% tracing but the tool runs a session, the node must be reinitiated to become
%% tracing.
reconnect_nodes() ->
    gen_server:call(?MODULE,{reconnect_nodes,local_runtime}).
reconnect_nodes(Node) when atom(Node) ->
    reconnect_nodes([Node]);
reconnect_nodes(Nodes) when list(Nodes) ->
    gen_server:call(?MODULE,{reconnect_nodes,Nodes}).
%% -----------------------------------------------------------------------------

%% start_session()={ok,{SessionNr,InvisoReturn}} | {error,Reason}
%% start_session(MoreTDGargs)=
%%   MoreTDGargs=list(), prepended to the fixed list of args used when calling the
%%     tracer data generator function.
%%   SessionNr=integer(), trace sessions are numbered by the tool.
%%   InvisoReturn=If successful inviso call, the returnvalue from inviso.
%%     Note that individual nodes may be unsuccessful. See inviso:init_tracing/1
%% Initiates tracing at all participating nodes.
start_session() ->
    start_session([]).
start_session(MoreTDGargs) ->
    gen_server:call(?MODULE,{start_session,MoreTDGargs}).
%% -----------------------------------------------------------------------------

%% reinitiate_session(Nodes)={ok,InvisoReturn} | {error,Reason}
%%   InvisoReturn=If successful inviso call, the returnvalue from inviso:init_tracing/1.
%%     Note that individual nodes may be unsuccessful. Mentioned nodes not part
%%       of the tool or not in state inactive will be marked as failing by the
%%       tool in the InvisoReturn.
%% To reinitate a node means to (inviso) init tracing at it according to saved
%% tracer data generator arguments for the current session and then redo the current
%% history to bring it up to speed. Note that the tool must be running a session
%% for reinitiate to work.
reinitiate_session() ->
    gen_server:call(?MODULE,{reinitiate_session,local_runtime}).
reinitiate_session(Nodes) ->
    gen_server:call(?MODULE,{reinitiate_session,Nodes}).
%% -----------------------------------------------------------------------------

%% restore_session()=
%% restore_session(MoreTDGargs)=
%% restore_session(FileName)=
%% restore_session(FileName,MoreTDGargs)={ok,{SessionNr,InvisoReturn}} | {error,Reason}
%% The two first clauses will start a new session using the last history. This
%% implies that there must have been a session running prior.
%% The two last clauses starts a session and reads a history file and executes the
%% tracecases in it at all inactive nodes.
%% In both cases the reused or read history becomes the current histoy, just if the
%% session had been initiated manually. The tool may not
%% have a session ongoing, and nodes already tracing (nodes which were adopted)
%% are not effected. Just like when starting a session manually.