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 report(Handle, TraceOrEvent) -> {ok, Continuation} | exit(Reason)
132 report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Con‐
133 tinuation} | exit(Reason)
134 report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok,
135 Continuation} | exit(Reason)
136 Types:
138 Handle = Initial | Continuation
140 Initial = collector_pid()
141 collector_pid() = pid()
142 Continuation = record(table_handle)
143 TraceOrEvent = record(event) | dbg_trace_tuple() |
144 end_of_trace
145 Reason = term()
146 DetailLevel = integer(X) when X =< 0, X >= 100
147 From = actor()
148 To = actor()
149 FromTo = actor()
150 Label = atom() | string() | term()
151 Contents = [{Key, Value}] | term()
152 actor() = term()
153 Report an event to the collector.
155 All events are filtered thru the collector filter, which option‐
157 ally may transform or discard the event. The first call should
158 use the pid of the collector process as report handle, while
159 subsequent calls should use the table handle.
160 make_key(Type, Stuff) -> Key
162 Types:
164 Type = record(table_handle) | trace_ts | event_ts
166 Stuff = record(event) | Key
167 Key = record(event_ts) | record(trace_ts)
168 Make a key out of an event record or an old key.
170 get_global_pid() -> CollectorPid | exit(Reason)
172 Types:
174 CollectorPid = pid()
176 Reason = term()
177 Return a the identity of the globally registered collector if
179 there is any.
180 change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
182 Types:
184 CollectorPid = pid()
186 RawPattern = {report_module(), extended_dbg_match_spec()}
187 report_module() = atom() | undefined
188 extended_dbg_match_spec() = detail_level() | dbg_match_spec()
189 RawPattern = detail_level()
190 detail_level() = min | max | integer(X) when X =< 0, X >= 100
191 TracePattern = {report_module(), dbg_match_spec_match_spec()}
192 Change active trace pattern globally on all trace nodes.
194 dict_insert(CollectorPid, {filter, collector}, FilterFun) -> ok
196 dict_insert(CollectorPid, {subscriber, SubscriberPid}, Void) -> ok
197 dict_insert(CollectorPid, Key, Val) -> ok
198 Types:
200 CollectorPid = pid()
202 FilterFun = filter_fun()
203 SubscriberPid = pid()
204 Void = term()
205 Key = term()
206 Val = term()
207 Insert a dictionary entry and send a {et, {dict_insert, Key,
209 Val}} tuple to all registered subscribers.
210 If the entry is a new subscriber, it will imply that the new
212 subscriber process first will get one message for each already
213 stored dictionary entry, before it and all old subscribers will
214 get this particular entry. The collector process links to and
215 then supervises the subscriber process. If the subscriber
216 process dies it will imply that it gets unregistered as with a
217 normal dict_delete/2.
218 dict_lookup(CollectorPid, Key) -> [Val]
220 Types:
222 CollectorPid = pid()
224 FilterFun = filter_fun()
225 CollectorPid = pid()
226 Key = term()
227 Val = term()
228 Lookup a dictionary entry and return zero or one value.
230 dict_delete(CollectorPid, Key) -> ok
232 Types:
234 CollectorPid = pid()
236 SubscriberPid = pid()
237 Key = {subscriber, SubscriberPid} | term()
238 Delete a dictionary entry and send a {et, {dict_delete, Key}}
240 tuple to all registered subscribers.
241 If the deleted entry is a registered subscriber, it will imply
243 that the subscriber process gets is unregistered as subscriber
244 as well as it gets it final message.
245 dict_match(CollectorPid, Pattern) -> [Match]
247 Types:
249 CollectorPid = pid()
251 Pattern = '_' | {key_pattern(), val_pattern()}
252 key_pattern() = ets_match_object_pattern()
253 val_pattern() = ets_match_object_pattern()
254 Match = {key(), val()}
255 key() = term()
256 val() = term()
257 Match some dictionary entries
259 multicast(_CollectorPid, Msg) -> ok
261 Types:
263 CollectorPid = pid()
265 CollectorPid = pid()
266 Msg = term()
267 Sends a message to all registered subscribers.
269 start_trace_client(CollectorPid, Type, Parameters) -> file_loaded |
271 {trace_client_pid, pid()} | exit(Reason)
272 Types:
274 Type = dbg_trace_client_type()
276 Parameters = dbg_trace_client_parameters()
277 Pid = dbg_trace_client_pid()
278 Load raw Erlang trace from a file, port or process.
280 iterate(Handle, Prev, Limit) -> NewAcc
282 Short for iterate(Handle, Prev, Limit, undefined, Prev) ->
284 NewAcc
285 iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
287 Types:
289 Handle = collector_pid() | table_handle()
291 Prev = first | last | event_key()
292 Limit = done() | forward() | backward()
293 collector_pid() = pid()
294 table_handle() = record(table_handle)
295 event_key() = record(event) | record(event_ts) |
296 record(trace_ts)
297 done() = 0
298 forward() = infinity | integer(X) where X > 0
299 backward() = '-infinity' | integer(X) where X < 0
300 Fun = fun(Event, Acc) -> NewAcc
301 Acc = NewAcc = term()
302 Iterate over the currently stored events.
304 Iterates over the currently stored events and applies a function
306 for each event. The iteration may be performed forwards or back‐
307 wards and may be limited to a maximum number of events
308 (abs(Limit)).
309 clear_table(Handle) -> ok
311 Types:
313 Handle = collector_pid() | table_handle()
315 collector_pid() = pid()
316 table_handle() = record(table_handle)
317 Clear the event table.
319Ericsson AB et 1.6.4 et_collector(3)