1et_collector(3) Erlang Module Definition et_collector(3)
2
6 et_collector - Collect trace events and provide a backing storage
7 appropriate 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(),
28 extended_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
55 option 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
60 reported events are first filtered thru the collector filter
61 before they are stored by the collector. By replacing the
62 default collector filter with a customized dito it is possible
63 to allow any trace data as input. The collector filter is a dic‐
64 tionary entry with the predefined key {filter, collector} and
65 the value is a fun of arity 1. See et_selector:make_event/1 for
66 interface details, such as which erlang:trace/1 tuples that are
67 accepted.
68 The collector has a built-in dictionary service. Any term may be
70 stored as value in the dictionary and bound to a unique key.
71 When new values are inserted with an existing key, the new val‐
72 ues will overwrite the existing ones. Processes may subscribe on
73 dictionary updates by using {subscriber, pid()} as dictionary
74 key. All dictionary updates will be propagated to the subscriber
75 processes matching the pattern {{subscriber, '_'}, '_'} where
76 the first '_' is interpreted as a pid().
77 In global trace mode, the collector will automatically start
79 tracing on all connected Erlang nodes. When a node connects, a
80 port tracer will be started on that node and a corresponding
81 trace client on the collector node.
82 Default values:
84 * parent_pid - self().
86 * event_order - trace_ts.
88 * trace_global - false.
90 * trace_pattern - undefined.
92 * trace_port - 4711.
94 * trace_max_queue - 50.
96 stop(CollectorPid) -> ok
98 Types:
100 CollectorPid = pid()
102 Stop a collector process.
104 save_event_file(CollectorPid, FileName, Options) -> ok | {error, Rea‐
106 son}
107 Types:
109 CollectorPid = pid()
111 FileName = string()
112 Options = [option()]
113 Reason = term()
114 option() = event_option() | file_option() | table_option()
115 event_option() = existing
116 file_option() = write | append
117 table_option() = keep | clear
118 Save the events to a file.
120 By default the currently stored events (existing) are written to
122 a brand new file (write) and the events are kept (keep) after
123 they have been written to the file.
124 Instead of keeping the events after writing them to file, it is
126 possible to remove all stored events after they have success‐
127 fully written to file (clear).
128 The options defaults to existing, write and keep.
130 load_event_file(CollectorPid, FileName) -> {ok, BadBytes} | exit(Rea‐
132 son)
133 Types:
135 CollectorPid = pid()
137 FileName = string()
138 BadBytes = integer(X) where X >= 0
139 Reason = term()
140 Load the event table from a file.
142 report(Handle, TraceOrEvent) -> {ok, Continuation} | exit(Reason)
144 report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Con‐
145 tinuation} | exit(Reason)
146 report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok,
147 Continuation} | exit(Reason)
148 Types:
150 Handle = Initial | Continuation
152 Initial = collector_pid()
153 collector_pid() = pid()
154 Continuation = record(table_handle)
155 TraceOrEvent = record(event) | dbg_trace_tuple() |
156 end_of_trace
157 Reason = term()
158 DetailLevel = integer(X) when X =< 0, X >= 100
159 From = actor()
160 To = actor()
161 FromTo = actor()
162 Label = atom() | string() | term()
163 Contents = [{Key, Value}] | term()
164 actor() = term()
165 Report an event to the collector.
167 All events are filtered thru the collector filter, which option‐
169 ally may transform or discard the event. The first call should
170 use the pid of the collector process as report handle, while
171 subsequent calls should use the table handle.
172 make_key(Type, Stuff) -> Key
174 Types:
176 Type = record(table_handle) | trace_ts | event_ts
178 Stuff = record(event) | Key
179 Key = record(event_ts) | record(trace_ts)
180 Make a key out of an event record or an old key.
182 get_table_handle(CollectorPid) -> Handle
184 Types:
186 CollectorPid = pid()
188 Handle = record(table_handle)
189 Return a table handle.
191 get_global_pid() -> CollectorPid | exit(Reason)
193 Types:
195 CollectorPid = pid()
197 Reason = term()
198 Return a the identity of the globally registered collector if
200 there is any.
201 change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
203 Types:
205 CollectorPid = pid()
207 RawPattern = {report_module(), extended_dbg_match_spec()}
208 report_module() = atom() | undefined
209 extended_dbg_match_spec() = detail_level() | dbg_match_spec()
210 RawPattern = detail_level()
211 detail_level() = min | max | integer(X) when X =< 0, X >= 100
212 TracePattern = {report_module(), dbg_match_spec_match_spec()}
213 Change active trace pattern globally on all trace nodes.
215 dict_insert(CollectorPid, {filter, collector}, FilterFun) -> ok
217 dict_insert(CollectorPid, {subscriber, SubscriberPid}, Void) -> ok
218 dict_insert(CollectorPid, Key, Val) -> ok
219 Types:
221 CollectorPid = pid()
223 FilterFun = filter_fun()
224 SubscriberPid = pid()
225 Void = term()
226 Key = term()
227 Val = term()
228 Insert a dictionary entry and send a {et, {dict_insert, Key,
230 Val}} tuple to all registered subscribers.
231 If the entry is a new subscriber, it will imply that the new
233 subscriber process first will get one message for each already
234 stored dictionary entry, before it and all old subscribers will
235 get this particular entry. The collector process links to and
236 then supervises the subscriber process. If the subscriber
237 process dies it will imply that it gets unregistered as with a
238 normal dict_delete/2.
239 dict_lookup(CollectorPid, Key) -> [Val]
241 Types:
243 CollectorPid = pid()
245 FilterFun = filter_fun()
246 CollectorPid = pid()
247 Key = term()
248 Val = term()
249 Lookup a dictionary entry and return zero or one value.
251 dict_delete(CollectorPid, Key) -> ok
253 Types:
255 CollectorPid = pid()
257 SubscriberPid = pid()
258 Key = {subscriber, SubscriberPid} | term()
259 Delete a dictionary entry and send a {et, {dict_delete, Key}}
261 tuple to all registered subscribers.
262 If the deleted entry is a registered subscriber, it will imply
264 that the subscriber process gets is unregistered as subscriber
265 as well as it gets it final message.
266 dict_match(CollectorPid, Pattern) -> [Match]
268 Types:
270 CollectorPid = pid()
272 Pattern = '_' | {key_pattern(), val_pattern()}
273 key_pattern() = ets_match_object_pattern()
274 val_pattern() = ets_match_object_pattern()
275 Match = {key(), val()}
276 key() = term()
277 val() = term()
278 Match some dictionary entries
280 multicast(_CollectorPid, Msg) -> ok
282 Types:
284 CollectorPid = pid()
286 CollectorPid = pid()
287 Msg = term()
288 Sends a message to all registered subscribers.
290 start_trace_client(CollectorPid, Type, Parameters) -> file_loaded |
292 {trace_client_pid, pid()} | exit(Reason)
293 Types:
295 Type = dbg_trace_client_type()
297 Parameters = dbg_trace_client_parameters()
298 Pid = dbg_trace_client_pid()
299 Load raw Erlang trace from a file, port or process.
301 iterate(Handle, Prev, Limit) -> NewAcc
303 Short for iterate(Handle, Prev, Limit, undefined, Prev) ->
305 NewAcc
306 iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
308 Types:
310 Handle = collector_pid() | table_handle()
312 Prev = first | last | event_key()
313 Limit = done() | forward() | backward()
314 collector_pid() = pid()
315 table_handle() = record(table_handle)
316 event_key() = record(event) | record(event_ts) |
317 record(trace_ts)
318 done() = 0
319 forward() = infinity | integer(X) where X > 0
320 backward() = '-infinity' | integer(X) where X < 0
321 Fun = fun(Event, Acc) -> NewAcc
322 Acc = NewAcc = term()
323 Iterate over the currently stored events.
325 Iterates over the currently stored events and applies a function
327 for each event. The iteration may be performed forwards or back‐
328 wards and may be limited to a maximum number of events
329 (abs(Limit)).
330 clear_table(Handle) -> ok
332 Types:
334 Handle = collector_pid() | table_handle()
336 collector_pid() = pid()
337 table_handle() = record(table_handle)
338 Clear the event table.
340Ericsson AB et 1.6.4 et_collector(3)