The R13B03 release.OTP_R13B03

1 files changed, 140 insertions, 0 deletions

diff --git a/lib/et/src/et.erl b/lib/et/src/et.erl
new file mode 100644
index 0000000000..9c0a7f8f49
--- /dev/null
+++ b/lib/et/src/et.erl
@@ -0,0 +1,140 @@
+%%
+%% %CopyrightBegin%
+%% 
+%% Copyright Ericsson AB 2000-2009. All Rights Reserved.
+%% 
+%% 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 online 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.
+%% 
+%% %CopyrightEnd%
+%%
+%%----------------------------------------------------------------------
+%% Purpose: Main API module for Event Tracer
+%%----------------------------------------------------------------------
+%%
+%% The Event Tracer (et) uses the built-in trace mechanism in Erlang and
+%% provides tools for collection and graphical viewing of trace data.
+%%
+%% et_collector
+%%
+%%   An Erlang trace client which collects and stores trace data.
+%%   Provides hooks for trace data filtering and group communication
+%%   between processes (such as et_viewer-processes). The trace data
+%%   is preferably traced et-module calls, but may in fact be any
+%%   Erlang trace data.
+%%
+%%   It do also provide functionality for global control of trace
+%%   pattern settings. If used, the one et_collector-process is
+%%   registered globally. On all connected Erlang nodes, it starts an
+%%   Erlang tracer process which sends its trace data to a local port
+%%   (the port number is generated). On the node where the global
+%%   et_collector is running, the corresponding Erlang trace client
+%%   processes are started (one for each node), configured to
+%%   transform the trace data into event records and possibly hand
+%%   them over to the collector. Whenever new nodes are
+%%   (dis)connected, this is monitored and new tracer/client pair of
+%%   processes are automatically started and eventually the trace
+%%   pattern are set on these nodes.
+%%
+%%   Trace data can also be loaded from one or more files.
+%%
+%% et_viewer
+%%
+%%   A graphical sequence chart tool. It is connected to a
+%%   et_collector-process, which it polls regulary for more trace
+%%   events to display. Before the event is displayed a user defined
+%%   filter function is applied in order to skip, accept as is or
+%%   transform the event. Several et_viewer-processes may share the
+%%   same et_collector in order to provide different simultaneous
+%%   views of the same trace data.
+%%   
+%% et_contents_viewer
+%%
+%%   A graphical tool which displays a detailed view of one trace
+%%   event. Normally started from the et_viewer.
+%%   
+%% et_selector
+%%
+%%   A library module with low level functions for activation of
+%%   Erlang trace patterns. It do also implement a default filter
+%%   function which transforms the raw trace data into the event
+%%   record data structure that is used as internal format by the rest
+%%   of the application. Customized transform functions can be
+%%   alternatively be used (by et_viewer, et_contents_viewer and
+%%   et_collector), if needed.
+%%   
+%% et
+%%
+%%   A library module with a few event report functions that are
+%%   intended to be invoked from other applications. The functions are
+%%   extremely light weight as they do nothing besides returning an
+%%   atom. These functions are specifically designed to be traced
+%%   for. The global trace patterns in et_collector defaults to trace
+%%   on these functions.
+%%----------------------------------------------------------------------
+
+-module(et).
+
+-export([
+	 phone_home/4, report_event/4,
+	 phone_home/5, report_event/5
+        ]).
+
+%%----------------------------------------------------------------------
+%% Reports an event, such as a message
+%%
+%% report_event(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
+%% report_event(DetailLevel, From, To, Label, Contents) -> hopefully_traced
+%% phone_home(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
+%% phone_home(DetailLevel, From, To, Label, Contents) -> hopefully_traced
+%%
+%% DetailLevel = integer(X) when X =< 0, X >= 100
+%% From        = actor()
+%% To          = actor()
+%% FromTo      = actor()
+%% Label       = atom() | string() |�term()
+%% Contents    = [{Key, Value}] | term()
+%%
+%% actor()  = term()
+%%
+%% These functions are intended to be invoked at strategic places
+%% in user applications in order to enable simplified tracing.
+%% The functions are extremely light weight as they do nothing
+%% besides returning an atom. These functions are designed for
+%% being traced. The global tracing mechanism in et_collector
+%% defaults to set its trace pattern to these functions.
+%%   
+%% The label is intended to provide a brief summary of the event.
+%% A simple tag would do.
+%%
+%% The contents can be any term but in order to simplify
+%% post processing of the traced events, a plain list
+%% of {Key, Value} tuples is preferred.
+%%
+%% Some events, such as messages, are directed from some actor to another.
+%% Other events (termed actions) may be undirected and only have one actor.
+%%----------------------------------------------------------------------
+
+phone_home(DetailLevel, FromTo, Label, Contents) ->
+    %% N.B External call
+    ?MODULE:report_event(DetailLevel, FromTo, FromTo, Label, Contents).
+
+phone_home(DetailLevel, From, To, Label, Contents) ->
+    %% N.B External call
+    ?MODULE:report_event(DetailLevel, From, To, Label, Contents).
+
+report_event(DetailLevel, FromTo, Label, Contents) ->
+    %% N.B External call
+    ?MODULE:report_event(DetailLevel, FromTo, FromTo, Label, Contents).
+
+report_event(DetailLevel, _From, _To, _Label, _Contents)
+  when integer(DetailLevel) ->
+    hopefully_traced.