diff options
Diffstat (limited to 'lib/et/src/et.erl')
| -rw-r--r-- | lib/et/src/et.erl | 140 |
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. |