1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2000-2012. 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([
trace_me/4, phone_home/4, report_event/4,
trace_me/5, phone_home/5, report_event/5
]).
%%----------------------------------------------------------------------
%% Reports an event, such as a message
%%
%% trace_me(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
%% trace_me(DetailLevel, From, To, Label, Contents) -> hopefully_traced
%% 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.
%%----------------------------------------------------------------------
trace_me(DetailLevel, FromTo, Label, Contents)
when is_integer(DetailLevel) ->
?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
trace_me(DetailLevel, _From, _To, _Label, _Contents)
when is_integer(DetailLevel) ->
hopefully_traced.
phone_home(DetailLevel, FromTo, Label, Contents) ->
%% N.B External call
?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
phone_home(DetailLevel, From, To, Label, Contents) ->
%% N.B External call
?MODULE:trace_me(DetailLevel, From, To, Label, Contents).
report_event(DetailLevel, FromTo, Label, Contents) ->
%% N.B External call
?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
report_event(DetailLevel, From, To, Label, Contents)
when is_integer(DetailLevel) ->
%% N.B External call
?MODULE:trace_me(DetailLevel, From, To, Label, Contents).
|
