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 <v>extended_dbg_match_spec()() = detail_level() |
31 dbg_match_spec()
32 detail_level() = min | max | integer(X) when X =< 0, X >= 100
33 trace_client() = {event_file, file_name()} |
34 {dbg_trace_type(), dbg_trace_parameters()}
35 file_name() = string()
36 collector_fun() = trace_filter_fun() | event_filter_fun()
37 trace_filter_fun() = fun(TraceData) -> false | true | {true,
38 NewEvent}
39 event_filter_fun() = fun(Event) -> false | true | {true, New‐
40 Event}
41 event_filter_name() = atom()
42 TraceData = erlang_trace_data()
43 Event = NewEvent = record(event)
44 dict_key() = term()
45 dict_val() = term()
46 CollectorPid = pid()
47 Reason = term()
48 Start a collector process.
50 The collector collects trace events and keeps them ordered by
52 their timestamp. The timestamp may either reflect the time when
53 the actual trace data was generated (trace_ts) or when the trace
54 data was transformed into an event record (event_ts). If the
55 time stamp is missing in the trace data (missing timestamp
56 option to erlang:trace/4) the trace_ts will be set to the
57 event_ts.
58 Events are reported to the collector directly with the report
60 function or indirectly via one or more trace clients. All
61 reported events are first filtered thru the collector filter
62 before they are stored by the collector. By replacing the
63 default collector filter with a customized dito it is possible
64 to allow any trace data as input. The collector filter is a dic‐
65 tionary entry with the predefined key {filter, collector} and
66 the value is a fun of arity 1. See et_selector:make_event/1 for
67 interface details, such as which erlang:trace/1 tuples that are
68 accepted.
69 The collector has a built-in dictionary service. Any term may be
71 stored as value in the dictionary and bound to a unique key.
72 When new values are inserted with an existing key, the new val‐
73 ues will overwrite the existing ones. Processes may subscribe on
74 dictionary updates by using {subscriber, pid()} as dictionary
75 key. All dictionary updates will be propagated to the subscriber
76 processes matching the pattern {{subscriber, '_'}, '_'} where
77 the first '_' is interpreted as a pid().
78 In global trace mode, the collector will automatically start
80 tracing on all connected Erlang nodes. When a node connects, a
81 port tracer will be started on that node and a corresponding
82 trace client on the collector node.
83 Default values:
85 * parent_pid - self().
87 * event_order - trace_ts.
89 * trace_global - false.
91 * trace_pattern - undefined.
93 * trace_port - 4711.
95 * trace_max_queue - 50.
97 stop(CollectorPid) -> ok
99 Types:
101 CollectorPid = pid()
103 Stop a collector process.
105 save_event_file(CollectorPid, FileName, Options) -> ok | {error, Rea‐
107 son}
108 Types:
110 CollectorPid = pid()
112 FileName = string()
113 Options = [option()]
114 Reason = term()
115 option() = event_option() | file_option() | table_option()
116 event_option() = existing
117 file_option() = write | append
118 table_option() = keep | clear
119 Save the events to a file.
121 By default the currently stored events (existing) are written to
123 a brand new file (write) and the events are kept (keep) after
124 they have been written to the file.
125 Instead of keeping the events after writing them to file, it is
127 possible to remove all stored events after they have success‐
128 fully written to file (clear).
129 The options defaults to existing, write and keep.
131 load_event_file(CollectorPid, FileName) -> {ok, BadBytes} | exit(Rea‐
133 son)
134 Types:
136 CollectorPid = pid()
138 FileName = string()
139 BadBytes = integer(X) where X >= 0
140 Reason = term()
141 Load the event table from a file.
143 report(Handle, TraceOrEvent) -> {ok, Continuation} | exit(Reason)
145 report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Con‐
146 tinuation} | exit(Reason)
147 report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok,
148 Continuation} | exit(Reason)
149 Types:
151 Handle = Initial | Continuation
153 Initial = collector_pid()
154 collector_pid() = pid()
155 Continuation = record(table_handle)
156 TraceOrEvent = record(event) | dbg_trace_tuple() |
157 end_of_trace
158 Reason = term()
159 DetailLevel = integer(X) when X =< 0, X >= 100
160 From = actor()
161 To = actor()
162 FromTo = actor()
163 Label = atom() | string() | term()
164 Contents = [{Key, Value}] | term()
165 actor() = term()
166 Report an event to the collector.
168 All events are filtered thru the collector filter, which option‐
170 ally may transform or discard the event. The first call should
171 use the pid of the collector process as report handle, while
172 subsequent calls should use the table handle.
173 make_key(Type, Stuff) -> Key
175 Types:
177 Type = record(table_handle) | trace_ts | event_ts
179 Stuff = record(event) | Key
180 Key = record(event_ts) | record(trace_ts)
181 Make a key out of an event record or an old key.
183 get_table_handle(CollectorPid) -> Handle
185 Types:
187 CollectorPid = pid()
189 Handle = record(table_handle)
190 Return a table handle.
192 get_global_pid() -> CollectorPid | exit(Reason)
194 Types:
196 CollectorPid = pid()
198 Reason = term()
199 Return a the identity of the globally registered collector if
201 there is any.
202 change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
204 Types:
206 CollectorPid = pid()
208 RawPattern = {report_module(), extended_dbg_match_spec()}
209 report_module() = atom() | undefined
210 extended_dbg_match_spec()() = detail_level() |
211 dbg_match_spec()
212 RawPattern = detail_level()
213 detail_level() = min | max | integer(X) when X =< 0, X >= 100
214 TracePattern = {report_module(), dbg_match_spec_match_spec()}
215 Change active trace pattern globally on all trace nodes.
217 dict_insert(CollectorPid, {filter, collector}, FilterFun) -> ok
219 dict_insert(CollectorPid, {subscriber, SubscriberPid}, Void) -> ok
220 dict_insert(CollectorPid, Key, Val) -> ok
221 Types:
223 CollectorPid = pid()
225 FilterFun = filter_fun()
226 SubscriberPid = pid()
227 Void = term()
228 Key = term()
229 Val = term()
230 Insert a dictionary entry and send a {et, {dict_insert, Key,
232 Val}} tuple to all registered subscribers.
233 If the entry is a new subscriber, it will imply that the new
235 subscriber process first will get one message for each already
236 stored dictionary entry, before it and all old subscribers will
237 get this particular entry. The collector process links to and
238 then supervises the subscriber process. If the subscriber
239 process dies it will imply that it gets unregistered as with a
240 normal dict_delete/2.
241 dict_lookup(CollectorPid, Key) -> [Val]
243 Types:
245 CollectorPid = pid()
247 FilterFun = filter_fun()
248 CollectorPid = pid()
249 Key = term()
250 Val = term()
251 Lookup a dictionary entry and return zero or one value.
253 dict_delete(CollectorPid, Key) -> ok
255 Types:
257 CollectorPid = pid()
259 SubscriberPid = pid()
260 Key = {subscriber, SubscriberPid} | term()
261 Delete a dictionary entry and send a {et, {dict_delete, Key}}
263 tuple to all registered subscribers.
264 If the deleted entry is a registered subscriber, it will imply
266 that the subscriber process gets is unregistered as subscriber
267 as well as it gets it final message.
268 dict_match(CollectorPid, Pattern) -> [Match]
270 Types:
272 CollectorPid = pid()
274 Pattern = '_' | {key_pattern(), val_pattern()}
275 key_pattern() = ets_match_object_pattern()
276 val_pattern() = ets_match_object_pattern()
277 Match = {key(), val()}
278 key() = term()
279 val() = term()
280 Match some dictionary entries
282 multicast(_CollectorPid, Msg) -> ok
284 Types:
286 CollectorPid = pid()
288 CollectorPid = pid()
289 Msg = term()
290 Sends a message to all registered subscribers.
292 start_trace_client(CollectorPid, Type, Parameters) -> file_loaded |
294 {trace_client_pid, pid()} | exit(Reason)
295 Types:
297 Type = dbg_trace_client_type()
299 Parameters = dbg_trace_client_parameters()
300 Pid = dbg_trace_client_pid()
301 Load raw Erlang trace from a file, port or process.
303 iterate(Handle, Prev, Limit) -> NewAcc
305 Short for iterate(Handle, Prev, Limit, undefined, Prev) ->
307 NewAcc
308 iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
310 Types:
312 Handle = collector_pid() | table_handle()
314 Prev = first | last | event_key()
315 Limit = done() | forward() | backward()
316 collector_pid() = pid()
317 table_handle() = record(table_handle)
318 event_key() = record(event) | record(event_ts) |
319 record(trace_ts)
320 done() = 0
321 forward() = infinity | integer(X) where X > 0
322 backward() = '-infinity' | integer(X) where X < 0
323 Fun = fun(Event, Acc) -> NewAcc <v>Acc = NewAcc = term()
324 Iterate over the currently stored events.
326 Iterates over the currently stored events and applies a function
328 for each event. The iteration may be performed forwards or back‐
329 wards and may be limited to a maximum number of events
330 (abs(Limit)).
331 clear_table(Handle) -> ok
333 Types:
335 Handle = collector_pid() | table_handle()
337 collector_pid() = pid()
338 table_handle() = record(table_handle)
339 Clear the event table.
341Ericsson AB et 1.6.1 et_collector(3)