1et_collector(3) Erlang Module Definition et_collector(3)
2
6 et_collector - Collect trace events and provide a backing storage ap‐
7 propriate for iteration
8
10 Interface module for the Event Trace (ET) application
11
13 start_link(Options) -> {ok, CollectorPid} | {error, Reason}
14 Types:
16 Options = [option()]
18 option() = {parent_pid, pid()} | {event_order, event_order()}
19 | {dict_insert, {filter, collector}, collector_fun()} |
20 {dict_insert, {filter, event_filter_name()}, event_fil‐
21 ter_fun()} | {dict_insert, {subscriber, pid()}, dict_val()} |
22 {dict_insert, dict_key(), dict_val()} | {dict_delete,
23 dict_key()} | {trace_client, trace_client()} | {trace_global,
24 boolean()} | {trace_pattern, trace_pattern()} | {trace_port,
25 integer()} | {trace_max_queue, integer()}
26 event_order() = trace_ts | event_ts
27 trace_pattern() = {report_module(), ex‐
28 tended_dbg_match_spec()} | undefined
29 report_module() = atom() | undefined
30 extended_dbg_match_spec() = detail_level() | dbg_match_spec()
31 detail_level() = min | max | integer(X) when X =< 0, X >= 100
32 trace_client() = {event_file, file_name()} |
33 {dbg_trace_type(), dbg_trace_parameters()}
34 file_name() = string()
35 collector_fun() = trace_filter_fun() | event_filter_fun()
36 trace_filter_fun() = fun(TraceData) -> false | true | {true,
37 NewEvent}
38 event_filter_fun() = fun(Event) -> false | true | {true, New‐
39 Event}
40 event_filter_name() = atom()
41 TraceData = erlang_trace_data()
42 Event = NewEvent = record(event)
43 dict_key() = term()
44 dict_val() = term()
45 CollectorPid = pid()
46 Reason = term()
47 Start a collector process.
49 The collector collects trace events and keeps them ordered by
51 their timestamp. The timestamp may either reflect the time when
52 the actual trace data was generated (trace_ts) or when the trace
53 data was transformed into an event record (event_ts). If the
54 time stamp is missing in the trace data (missing timestamp op‐
55 tion to erlang:trace/4) the trace_ts will be set to the
56 event_ts.
57 Events are reported to the collector directly with the report
59 function or indirectly via one or more trace clients. All re‐
60 ported events are first filtered thru the collector filter be‐
61 fore they are stored by the collector. By replacing the default
62 collector filter with a customized dito it is possible to allow
63 any trace data as input. The collector filter is a dictionary
64 entry with the predefined key {filter, collector} and the value
65 is a fun of arity 1. See et_selector:make_event/1 for interface
66 details, such as which erlang:trace/1 tuples that are accepted.
67 The collector has a built-in dictionary service. Any term may be
69 stored as value in the dictionary and bound to a unique key.
70 When new values are inserted with an existing key, the new val‐
71 ues will overwrite the existing ones. Processes may subscribe on
72 dictionary updates by using {subscriber, pid()} as dictionary
73 key. All dictionary updates will be propagated to the subscriber
74 processes matching the pattern {{subscriber, '_'}, '_'} where
75 the first '_' is interpreted as a pid().
76 In global trace mode, the collector will automatically start
78 tracing on all connected Erlang nodes. When a node connects, a
79 port tracer will be started on that node and a corresponding
80 trace client on the collector node.
81 Default values:
83 * parent_pid - self().
85 * event_order - trace_ts.
87 * trace_global - false.
89 * trace_pattern - undefined.
91 * trace_port - 4711.
93 * trace_max_queue - 50.
95 stop(CollectorPid) -> ok
97 Types:
99 CollectorPid = pid()
101 Stop a collector process.
103 save_event_file(CollectorPid, FileName, Options) -> ok | {error, Rea‐
105 son}
106 Types:
108 CollectorPid = pid()
110 FileName = string()
111 Options = [option()]
112 Reason = term()
113 option() = event_option() | file_option() | table_option()
114 event_option() = existing
115 file_option() = write | append
116 table_option() = keep | clear
117 Save the events to a file.
119 By default the currently stored events (existing) are written to
121 a brand new file (write) and the events are kept (keep) after
122 they have been written to the file.
123 Instead of keeping the events after writing them to file, it is
125 possible to remove all stored events after they have success‐
126 fully written to file (clear).
127 The options defaults to existing, write and keep.
129 report(Handle, TraceOrEvent) -> {ok, Continuation} | exit(Reason)
131 report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Con‐
132 tinuation} | exit(Reason)
133 report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok,
134 Continuation} | exit(Reason)
135 Types:
137 Handle = Initial | Continuation
139 Initial = collector_pid()
140 collector_pid() = pid()
141 Continuation = record(table_handle)
142 TraceOrEvent = record(event) | dbg_trace_tuple() |
143 end_of_trace
144 Reason = term()
145 DetailLevel = integer(X) when X =< 0, X >= 100
146 From = actor()
147 To = actor()
148 FromTo = actor()
149 Label = atom() | string() | term()
150 Contents = [{Key, Value}] | term()
151 actor() = term()
152 Report an event to the collector.
154 All events are filtered thru the collector filter, which option‐
156 ally may transform or discard the event. The first call should
157 use the pid of the collector process as report handle, while
158 subsequent calls should use the table handle.
159 make_key(Type, Stuff) -> Key
161 Types:
163 Type = record(table_handle) | trace_ts | event_ts
165 Stuff = record(event) | Key
166 Key = record(event_ts) | record(trace_ts)
167 Make a key out of an event record or an old key.
169 get_global_pid() -> CollectorPid | exit(Reason)
171 Types:
173 CollectorPid = pid()
175 Reason = term()
176 Return a the identity of the globally registered collector if
178 there is any.
179 change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
181 Types:
183 CollectorPid = pid()
185 RawPattern = {report_module(), extended_dbg_match_spec()}
186 report_module() = atom() | undefined
187 extended_dbg_match_spec() = detail_level() | dbg_match_spec()
188 RawPattern = detail_level()
189 detail_level() = min | max | integer(X) when X =< 0, X >= 100
190 TracePattern = {report_module(), dbg_match_spec_match_spec()}
191 Change active trace pattern globally on all trace nodes.
193 dict_insert(CollectorPid, {filter, collector}, FilterFun) -> ok
195 dict_insert(CollectorPid, {subscriber, SubscriberPid}, Void) -> ok
196 dict_insert(CollectorPid, Key, Val) -> ok
197 Types:
199 CollectorPid = pid()
201 FilterFun = filter_fun()
202 SubscriberPid = pid()
203 Void = term()
204 Key = term()
205 Val = term()
206 Insert a dictionary entry and send a {et, {dict_insert, Key,
208 Val}} tuple to all registered subscribers.
209 If the entry is a new subscriber, it will imply that the new
211 subscriber process first will get one message for each already
212 stored dictionary entry, before it and all old subscribers will
213 get this particular entry. The collector process links to and
214 then supervises the subscriber process. If the subscriber
215 process dies it will imply that it gets unregistered as with a
216 normal dict_delete/2.
217 dict_lookup(CollectorPid, Key) -> [Val]
219 Types:
221 CollectorPid = pid()
223 FilterFun = filter_fun()
224 CollectorPid = pid()
225 Key = term()
226 Val = term()
227 Lookup a dictionary entry and return zero or one value.
229 dict_delete(CollectorPid, Key) -> ok
231 Types:
233 CollectorPid = pid()
235 SubscriberPid = pid()
236 Key = {subscriber, SubscriberPid} | term()
237 Delete a dictionary entry and send a {et, {dict_delete, Key}}
239 tuple to all registered subscribers.
240 If the deleted entry is a registered subscriber, it will imply
242 that the subscriber process gets is unregistered as subscriber
243 as well as it gets it final message.
244 dict_match(CollectorPid, Pattern) -> [Match]
246 Types:
248 CollectorPid = pid()
250 Pattern = '_' | {key_pattern(), val_pattern()}
251 key_pattern() = ets_match_object_pattern()
252 val_pattern() = ets_match_object_pattern()
253 Match = {key(), val()}
254 key() = term()
255 val() = term()
256 Match some dictionary entries
258 multicast(_CollectorPid, Msg) -> ok
260 Types:
262 CollectorPid = pid()
264 CollectorPid = pid()
265 Msg = term()
266 Sends a message to all registered subscribers.
268 start_trace_client(CollectorPid, Type, Parameters) -> file_loaded |
270 {trace_client_pid, pid()} | exit(Reason)
271 Types:
273 Type = dbg_trace_client_type()
275 Parameters = dbg_trace_client_parameters()
276 Pid = dbg_trace_client_pid()
277 Load raw Erlang trace from a file, port or process.
279 iterate(Handle, Prev, Limit) -> NewAcc
281 Short for iterate(Handle, Prev, Limit, undefined, Prev) ->
283 NewAcc
284 iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
286 Types:
288 Handle = collector_pid() | table_handle()
290 Prev = first | last | event_key()
291 Limit = done() | forward() | backward()
292 collector_pid() = pid()
293 table_handle() = record(table_handle)
294 event_key() = record(event) | record(event_ts) |
295 record(trace_ts)
296 done() = 0
297 forward() = infinity | integer(X) where X > 0
298 backward() = '-infinity' | integer(X) where X < 0
299 Fun = fun(Event, Acc) -> NewAcc
300 Acc = NewAcc = term()
301 Iterate over the currently stored events.
303 Iterates over the currently stored events and applies a function
305 for each event. The iteration may be performed forwards or back‐
306 wards and may be limited to a maximum number of events
307 (abs(Limit)).
308 clear_table(Handle) -> ok
310 Types:
312 Handle = collector_pid() | table_handle()
314 collector_pid() = pid()
315 table_handle() = record(table_handle)
316 Clear the event table.
318Ericsson AB et 1.6.5 et_collector(3)