aboutsummaryrefslogtreecommitdiffstats
path: root/lib/et/doc/src/et_collector.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/et/doc/src/et_collector.xml')
-rw-r--r--lib/et/doc/src/et_collector.xml374
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&aring;kan Mattsson</prepared>
+ <responsible>H&aring;kan Mattsson</responsible>
+ <docno></docno>
+ <approved>H&aring;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 &lt;v>extended_dbg_match_spec()() = detail_level() | dbg_match_spec()</v>
+ <v>detail_level() = min | max | integer(X) when X =&lt; 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 =&lt; 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 =&lt; 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) -&gt; 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 &lt; 0</v>
+ <v>Fun = fun(Event, Acc) -> NewAcc &lt;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>
+
+