diff options
Diffstat (limited to 'lib/et/doc/src/et_collector.xml')
| -rw-r--r-- | lib/et/doc/src/et_collector.xml | 374 |
1 files changed, 374 insertions, 0 deletions
diff --git a/lib/et/doc/src/et_collector.xml b/lib/et/doc/src/et_collector.xml new file mode 100644 index 0000000000..01ca7caa5b --- /dev/null +++ b/lib/et/doc/src/et_collector.xml @@ -0,0 +1,374 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2002</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>et_collector</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date></date> + <rev>%VSN%</rev> + </header> + <module>et_collector</module> + <modulesummary>Collect trace events and provide a backing storage appropriate for iteration </modulesummary> + <description> + <p>Interface module for the Event Trace (ET) application</p> + </description> + <funcs> + <func> + <name>start_link(Options) -> {ok, CollectorPid} | {error, Reason}</name> + <fsummary>Start a collector process</fsummary> + <type> + <v>Options = [option()]</v> + <v>option() = {parent_pid, pid()} | {event_order, event_order()} | {dict_insert, {filter, collector}, collector_fun()} | {dict_insert, {filter, event_filter_name()}, event_filter_fun()} | {dict_insert, {subscriber, pid()}, dict_val()} | {dict_insert, dict_key(), dict_val()} | {dict_delete, dict_key()} | {trace_client, trace_client()} | {trace_global, boolean()} | {trace_pattern, trace_pattern()} | {trace_port, integer()} | {trace_max_queue, integer()}</v> + <v>event_order() = trace_ts | event_ts</v> + <v>trace_pattern() = {report_module(), extended_dbg_match_spec()} | undefined</v> + <v>report_module() = atom() | undefined <v>extended_dbg_match_spec()() = detail_level() | dbg_match_spec()</v> + <v>detail_level() = min | max | integer(X) when X =< 0, X >= 100</v> + <v>trace_client() = {event_file, file_name()} | {dbg_trace_type(), dbg_trace_parameters()}</v> + <v>file_name() = string()</v> + <v>collector_fun() = trace_filter_fun() | event_filter_fun()</v> + <v>trace_filter_fun() = fun(TraceData) -> false | true | {true, NewEvent}</v> + <v>event_filter_fun() = fun(Event) -> false | true | {true, NewEvent}</v> + <v>event_filter_name() = atom()</v> + <v>TraceData = erlang_trace_data()</v> + <v>Event = NewEvent = record(event)</v> + <v>dict_key() = term()</v> + <v>dict_val() = term()</v> + <v>CollectorPid = pid()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Start a collector process.</p> + <p>The collector collects trace events and keeps them ordered by their + timestamp. The timestamp may either reflect the time when the + actual trace data was generated (trace_ts) or when the trace data + was transformed into an event record (event_ts). If the time stamp + is missing in the trace data (missing timestamp option to + erlang:trace/4) the trace_ts will be set to the event_ts.</p> + <p>Events are reported to the collector directly with the report + function or indirectly via one or more trace clients. All reported + events are first filtered thru the collector filter before they are + stored by the collector. By replacing the default collector filter + with a customized dito it is possible to allow any trace data as + input. The collector filter is a dictionary entry with the + predefined key {filter, collector} and the value is a fun of + arity 1. See et_selector:make_event/1 for interface details, + such as which erlang:trace/1 tuples that are accepted.</p> + <p>The collector has a built-in dictionary service. Any term may be + stored as value in the dictionary and bound to a unique key. When + new values are inserted with an existing key, the new values will + overwrite the existing ones. Processes may subscribe on dictionary + updates by using {subscriber, pid()} as dictionary key. All + dictionary updates will be propagated to the subscriber processes + matching the pattern {{subscriber, '_'}, '_'} where the first '_' + is interpreted as a pid().</p> + <p>In global trace mode, the collector will automatically start + tracing on all connected Erlang nodes. When a node connects, a port + tracer will be started on that node and a corresponding trace + client on the collector node. By default the global trace pattern + is 'max'.</p> + <p>Default values:</p> + <list type="bulleted"> + <item>parent_pid - self().</item> + <item>event_order - trace_ts.</item> + <item>trace_global - false.</item> + <item>trace_pattern - undefined.</item> + <item>trace_port - 4711.</item> + <item>trace_max_queue - 50.</item> + </list> + </desc> + </func> + <func> + <name>stop(CollectorPid) -> ok</name> + <fsummary>Stop a collector process</fsummary> + <type> + <v>CollectorPid = pid()</v> + </type> + <desc> + <p>Stop a collector process.</p> + </desc> + </func> + <func> + <name>save_event_file(CollectorPid, FileName, Options) -> ok | {error, Reason}</name> + <fsummary>Save the events to a file</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>FileName = string()</v> + <v>Options = [option()]</v> + <v>Reason = term()</v> + <v>option() = event_option() | file_option() | table_option()</v> + <v>event_option() = existing</v> + <v>file_option() = write | append</v> + <v>table_option() = keep | clear</v> + </type> + <desc> + <p>Save the events to a file.</p> + <p>By default the currently stored events (existing) are + written to a brand new file (write) and the events are + kept (keep) after they have been written to the file.</p> + <p>Instead of keeping the events after writing them to file, + it is possible to remove all stored events after they + have successfully written to file (clear).</p> + <p>The options defaults to existing, write and keep.</p> + </desc> + </func> + <func> + <name>load_event_file(CollectorPid, FileName) -> {ok, BadBytes} | exit(Reason)</name> + <fsummary>Load the event table from a file</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>FileName = string()</v> + <v>BadBytes = integer(X) where X >= 0</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Load the event table from a file.</p> + </desc> + </func> + <func> + <name>report(Handle, TraceOrEvent) -> {ok, Continuation} | exit(Reason)</name> + <name>report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Continuation} | exit(Reason)</name> + <name>report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok, Continuation} | exit(Reason)</name> + <fsummary>Report an event to the collector</fsummary> + <type> + <v>Handle = Initial | Continuation</v> + <v>Initial = collector_pid()</v> + <v>collector_pid() = pid()</v> + <v>Continuation = record(table_handle)</v> + <v>TraceOrEvent = record(event) | dbg_trace_tuple() | end_of_trace</v> + <v>Reason = term()</v> + <v>DetailLevel = integer(X) when X =< 0, X >= 100</v> + <v>From = actor()</v> + <v>To = actor()</v> + <v>FromTo = actor()</v> + <v>Label = atom() | string() | term()</v> + <v>Contents = [{Key, Value}] | term()</v> + <v>actor() = term()</v> + </type> + <desc> + <p>Report an event to the collector.</p> + <p>All events are filtered thru the collector filter, which + optionally may transform or discard the event. The first + call should use the pid of the collector process as + report handle, while subsequent calls should use the + table handle.</p> + </desc> + </func> + <func> + <name>make_key(Type, Stuff) -> Key</name> + <fsummary>Make a key out of an event record or an old key</fsummary> + <type> + <v>Type = record(table_handle) | trace_ts | event_ts</v> + <v>Stuff = record(event) | Key</v> + <v>Key = record(event_ts) | record(trace_ts)</v> + </type> + <desc> + <p>Make a key out of an event record or an old key.</p> + </desc> + </func> + <func> + <name>get_table_handle(CollectorPid) -> Handle</name> + <fsummary>Return a table handle</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>Handle = record(table_handle)</v> + </type> + <desc> + <p>Return a table handle.</p> + </desc> + </func> + <func> + <name>get_global_pid() -> CollectorPid | exit(Reason)</name> + <fsummary>Return a the identity of the globally registered collector if there is any</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Return a the identity of the globally registered + collector if there is any.</p> + </desc> + </func> + <func> + <name>change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}</name> + <fsummary>Change active trace pattern globally on all trace nodes</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>RawPattern = {report_module(), extended_dbg_match_spec()}</v> + <v>report_module() = atom() | undefined</v> + <v>extended_dbg_match_spec()() = detail_level() | dbg_match_spec()</v> + <v>RawPattern = detail_level()</v> + <v>detail_level() = min | max | integer(X) when X =< 0, X >= 100</v> + <v>TracePattern = {report_module(), dbg_match_spec_match_spec()}</v> + </type> + <desc> + <p>Change active trace pattern globally on all trace nodes.</p> + </desc> + </func> + <func> + <name>dict_insert(CollectorPid, {filter, collector}, FilterFun) -> ok</name> + <name>dict_insert(CollectorPid, {subscriber, SubscriberPid}, Void) -> ok</name> + <name>dict_insert(CollectorPid, Key, Val) -> ok</name> + <fsummary>Insert a dictionary entry and send a {et, {dict_insert, Key, Val}} tuple to all registered subscribers.</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>FilterFun = filter_fun() </v> + <v>SubscriberPid = pid()</v> + <v>Void = term()</v> + <v>Key = term()</v> + <v>Val = term()</v> + </type> + <desc> + <p>Insert a dictionary entry + and send a {et, {dict_insert, Key, Val}} tuple + to all registered subscribers.</p> + <p>If the entry is a new subscriber, it will imply that + the new subscriber process first will get one message + for each already stored dictionary entry, before it + and all old subscribers will get this particular entry. + The collector process links to and then supervises the + subscriber process. If the subscriber process dies it + will imply that it gets unregistered as with a normal + dict_delete/2.</p> + </desc> + </func> + <func> + <name>dict_lookup(CollectorPid, Key) -> [Val]</name> + <fsummary>Lookup a dictionary entry and return zero or one value</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>FilterFun = filter_fun() </v> + <v>CollectorPid = pid()</v> + <v>Key = term()</v> + <v>Val = term()</v> + </type> + <desc> + <p>Lookup a dictionary entry and return zero or one value.</p> + </desc> + </func> + <func> + <name>dict_delete(CollectorPid, Key) -> ok</name> + <fsummary>Delete a dictionary entry and send a {et, {dict_delete, Key}} tuple to all registered subscribers.</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>SubscriberPid = pid()</v> + <v>Key = {subscriber, SubscriberPid} | term()</v> + </type> + <desc> + <p>Delete a dictionary entry + and send a {et, {dict_delete, Key}} tuple + to all registered subscribers.</p> + <p>If the deleted entry is a registered subscriber, it will + imply that the subscriber process gets is unregistered as + subscriber as well as it gets it final message.</p> + </desc> + </func> + <func> + <name>dict_match(CollectorPid, Pattern) -> [Match]</name> + <fsummary>Match some dictionary entries</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>Pattern = '_' | {key_pattern(), val_pattern()}</v> + <v>key_pattern() = ets_match_object_pattern()</v> + <v>val_pattern() = ets_match_object_pattern()</v> + <v>Match = {key(), val()}</v> + <v>key() = term()</v> + <v>val() = term()</v> + </type> + <desc> + <p>Match some dictionary entries</p> + </desc> + </func> + <func> + <name>multicast(_CollectorPid, Msg) -> ok</name> + <fsummary>Sends a message to all registered subscribers</fsummary> + <type> + <v>CollectorPid = pid()</v> + <v>CollectorPid = pid()</v> + <v>Msg = term()</v> + </type> + <desc> + <p>Sends a message to all registered subscribers.</p> + </desc> + </func> + <func> + <name>start_trace_client(CollectorPid, Type, Parameters) -> file_loaded | {trace_client_pid, pid()} | exit(Reason)</name> + <fsummary>Load raw Erlang trace from a file, port or process.</fsummary> + <type> + <v>Type = dbg_trace_client_type()</v> + <v>Parameters = dbg_trace_client_parameters()</v> + <v>Pid = dbg_trace_client_pid()</v> + </type> + <desc> + <p>Load raw Erlang trace from a file, port or process.</p> + </desc> + </func> + <func> + <name>iterate(Handle, Prev, Limit) -> NewAcc</name> + <fsummary>Iterates over the currently stored events</fsummary> + <desc> + <p>Short for iterate(Handle, Prev, Limit, undefined, Prev) -> NewAcc</p> + </desc> + </func> + <func> + <name>iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc</name> + <fsummary>Iterate over the currently stored events</fsummary> + <type> + <v>Handle = collector_pid() | table_handle()</v> + <v>Prev = first | last | event_key()</v> + <v>Limit = done() | forward() | backward()</v> + <v>collector_pid() = pid()</v> + <v>table_handle() = record(table_handle)</v> + <v>event_key() = record(event) | record(event_ts) | record(trace_ts)</v> + <v>done() = 0</v> + <v>forward() = infinity | integer(X) where X > 0</v> + <v>backward() = '-infinity' | integer(X) where X < 0</v> + <v>Fun = fun(Event, Acc) -> NewAcc <v>Acc = NewAcc = term()</v> + </type> + <desc> + <p>Iterate over the currently stored events.</p> + <p>Iterates over the currently stored eventsand applies + a function for each event. The iteration may be performed + forwards or backwards and may be limited to a maximum + number of events (abs(Limit)).</p> + </desc> + </func> + <func> + <name>clear_table(Handle) -> ok</name> + <fsummary>Clear the event table</fsummary> + <type> + <v>Handle = collector_pid() | table_handle()</v> + <v>collector_pid() = pid()</v> + <v>table_handle() = record(table_handle)</v> + </type> + <desc> + <p>Clear the event table.</p> + </desc> + </func> + </funcs> + +</erlref> + + |