aboutsummaryrefslogtreecommitdiffstats
path: root/lib/et/doc/src/et_examples.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/et/doc/src/et_examples.xml')
-rw-r--r--lib/et/doc/src/et_examples.xml311
1 files changed, 311 insertions, 0 deletions
diff --git a/lib/et/doc/src/et_examples.xml b/lib/et/doc/src/et_examples.xml
new file mode 100644
index 0000000000..7627b191a1
--- /dev/null
+++ b/lib/et/doc/src/et_examples.xml
@@ -0,0 +1,311 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <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>Examples</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>
+ <file>et_examples.xml</file>
+ </header>
+
+ <section>
+ <title>A simulated Mnesia transaction</title>
+ <p>The Erlang code for running the simulated Mnesia transaction example
+ in the previous chapter is included in the <c>et/examples/et_demo.erl</c> file:
+ </p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%sim_trans" type="erl"></codeinclude>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%mgr_actors" type="erl"></codeinclude>
+ <p>If you invoke the <c>et_demo:sim_trans()</c> function a viewer
+ window will pop up and the sequence trace will be almost the same as
+ if the following Mnesia transaction would have been run:</p>
+ <p></p>
+ <code type="none">
+ mnesia:transaction(fun() -> mnesia:write({my_tab, key, val}) end).
+ </code>
+ <p>And the viewer window will look like:</p>
+ <p></p>
+ <code type="none"><![CDATA[
+ $ erl -pa ../examples
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ 1> et_demo:sim_trans().
+ {ok,{table_handle,<0.30.0>,11,trace_ts,#Fun<et_collector.0.83904657>}}
+ 2>
+ ]]></code>
+ <p></p>
+ <image file="sim_trans.gif">
+ <icaption>A simulated Mnesia transaction which writes one record</icaption>
+ </image>
+ </section>
+
+ <section>
+ <title>Some convenient functions used in the Mnesia transaction example</title>
+ <p>The <c>module_as_actor</c> filter converts the event-records so
+ the module names becomes actors and the invoked functions becomes
+ labels. If the information about who the caller was it will be
+ displayed as an arrow directed from the caller to the callee. The
+ <c>[{message, {caller}}, {return_trace}]</c> options to <c>dbg:tpl/2</c>
+ function will imply the necessary information in the Erlang traces.
+ Here follows the <c>module_as_actor</c> filter:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%module_as_actor" type="erl"></codeinclude>
+ <p>The <c>plain_process_info</c> filter does not alter the event-records.
+ It merely ensures that the event not related to processes are skipped:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%plain_process_info" type="erl"></codeinclude>
+ <p>The <c>plain_process_info_nolink</c> filter does not alter the
+ event-records. It do makes use of the <c>plain_process_info</c> , but
+ do also ensure that the process info related to linking and unlinking
+ is skipped:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%plain_process_info_nolink" type="erl"></codeinclude>
+ <p>In order to simplify the startup of an <c>et_viewer</c> process
+ with the filters mentioned above, plus some others (that also are
+ found in <c>et/examples/et_demo.erl</c> src/et_collector.erl the
+ <c>et_demo:start/0,1</c> functions can be used:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%start" type="erl"></codeinclude>
+ <p>A simple one-liner starts the tool:</p>
+ <code type="none">
+ erl -pa ../examples -s et_demo
+ </code>
+ <p>The filters are included by the following parameters:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%filters" type="erl"></codeinclude>
+ </section>
+
+ <section>
+ <title>Erlang trace of a Mnesia transaction</title>
+ <p>The following piece of code <c>et_demo:trace_mnesia/0</c>
+ activates call tracing of both local and external function calls for
+ all modules in the Mnesia application. The call traces are configured
+ cover all processes (both existing and those that are spawned in the
+ future) and include timestamps for trace data. It do also activate
+ tracing of process related events for Mnesia's static processes plus
+ the calling process (that is your shell). Please, observe that the
+ <c>whereis/1</c> call in the following code requires that both the
+ traced Mnesia application and the <c>et_viewer</c>is running on the
+ same node:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%trace_mnesia" type="erl"></codeinclude>
+ <p>The <c>et_demo:live_trans/0</c> function starts the a global
+ controller, starts a viewer, starts Mnesia, creates a local table,
+ activates tracing (as described above) and registers the shell
+ process is as 'my_shell' for clarity. Finally the a simple Mnesia
+ transaction that writes a single record is run:</p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%live_trans" type="erl"></codeinclude>
+ <p>Now we run the <c>et_demo:live_trans/0</c> function:</p>
+ <p></p>
+ <code type="none">
+ erl -pa ../examples -s et_demo live_trans
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ 1>
+ </code>
+ <p>Please, explore the different filters in order to see how the traced
+ transaction can be seen from different point of views:</p>
+ <p></p>
+ <image file="live_trans.gif">
+ <icaption>A real Mnesia transaction which writes one record</icaption>
+ </image>
+ </section>
+
+ <section>
+ <title>Erlang trace of Megaco startup</title>
+ <p>The Event Tracer (ET) tool was initially written in order to
+ demonstrate how messages where sent over the Megaco protocol. This
+ were back in the old days before the standard bodies of IETF and ITU
+ had approved Megaco (also called H.248) as an international
+ standard.</p>
+ <p>In the Megaco application of Erlang/OTP, the code is carefully
+ instrumented with calls to <c>et:report_event/5</c>. For call a detail
+ level is set in order to dynamically control the trace level in a
+ simple manner.</p>
+ <p>The <c>megaco_filter</c> module implements a customized filter
+ for Megaco messages. It does also make use of <c>trace_global</c>
+ combined with usage of the <c>trace_pattern</c>:</p>
+ <p></p>
+ <code type="none">
+ -module(megaco_filter).
+ -export([start/0]).
+
+ start() ->
+ Options =
+ [{event_order, event_ts},
+ {scale, 3},
+ {max_actors, infinity},
+ {trace_pattern, {megaco, max}},
+ {trace_global, true},
+ {dict_insert, {filter, megaco_filter}, fun filter/1},
+ {active_filter, megaco_filter},
+ {title, "Megaco tracer - Erlang/OTP"}],
+ et_viewer:start(Options).
+ </code>
+ <p>First we start an Erlang node with the a global collector and
+ its viewer. The <c>et_viewer: search for: [] ++ ["gateway_tt"]</c>
+ printout is caused by a click on the "gateway_tt" actor name in the
+ viewer. It means that only events with that actor will be displayed
+ in the viewer.</p>
+ <p></p>
+ <code type="none">
+ erl -sname observer -s megaco_filter
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ (observer@amrod)1> et_viewer: search for: [] ++ ["gateway_tt"]
+ </code>
+ <p>Secondly we start another Erlang node which we connect the
+ observer node, before we start the application that we want to
+ trace. In this case we start a Media Gateway Controller that listens
+ for both TCP and UDP on the text and binary ports for Megaco:</p>
+ <p></p>
+ <code type="none">
+ erl -sname mgc -pa ../../megaco/examples/simple
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ (mgc@amrod)1> net:ping(observer@amrod).
+ pong
+ (mgc@amrod)2> megaco:start().
+ ok
+ (mgc@amrod)3> megaco_simple_mgc:start().
+ {ok,[{ok,2944,
+ {megaco_receive_handle,{deviceName,"controller"},
+ megaco_pretty_text_encoder,
+ [],
+ megaco_tcp}},
+ {ok,2944,
+ {megaco_receive_handle,{deviceName,"controller"},
+ megaco_pretty_text_encoder,
+ [],
+ megaco_udp}},
+ {ok,2945,
+ {megaco_receive_handle,{deviceName,"controller"},
+ megaco_binary_encoder,
+ [],
+ megaco_tcp}},
+ {ok,2945,
+ {megaco_receive_handle,{deviceName,"controller"},
+ megaco_binary_encoder,
+ [],
+ megaco_udp}}]}
+ (mgc@amrod)4>
+ </code>
+ <p>And finally we start an Erlang node for the Media Gateways and
+ connect to the observer node. Each Media Gateway connects to the
+ controller and sends an initial Service Change message. The controller
+ accepts the gateways and sends a reply to each one using the same
+ transport mechanism and message encoding according to the preference
+ of each gateway. That is all combinations of TCP/IP transport, UDP/IP
+ transport, text encoding and ASN.1 BER encoding:</p>
+ <p></p>
+ <code type="none">
+ erl -sname mg -pa ../../megaco/examples/simple
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ (mg@amrod)1> net:ping(observer@amrod).
+ pong
+ (mg@amrod)2> megaco_simple_mg:start().
+ [{{deviceName,"gateway_tt"},{error,{start_user,megaco_not_started}}},
+ {{deviceName,"gateway_tb"},{error,{start_user,megaco_not_started}}},
+ {{deviceName,"gateway_ut"},{error,{start_user,megaco_not_started}}},
+ {{deviceName,"gateway_ub"},{error,{start_user,megaco_not_started}}}]
+ (mg@amrod)3> megaco:start().
+ ok
+ (mg@amrod)4> megaco_simple_mg:start().
+ [{{deviceName,"gateway_tt"},
+ {1,
+ {ok,[{'ActionReply',0,
+ asn1_NOVALUE,
+ asn1_NOVALUE,
+ [{serviceChangeReply,
+ {'ServiceChangeReply',
+ [{megaco_term_id,false,["root"]}],
+ {serviceChangeResParms,
+ {'ServiceChangeResParm',
+ {deviceName|...},
+ asn1_NOVALUE|...}}}}]}]}}},
+ {{deviceName,"gateway_tb"},
+ {1,
+ {ok,[{'ActionReply',0,
+ asn1_NOVALUE,
+ asn1_NOVALUE,
+ [{serviceChangeReply,
+ {'ServiceChangeReply',
+ [{megaco_term_id,false,["root"]}],
+ {serviceChangeResParms,
+ {'ServiceChangeResParm',
+ {...}|...}}}}]}]}}},
+ {{deviceName,"gateway_ut"},
+ {1,
+ {ok,[{'ActionReply',0,
+ asn1_NOVALUE,
+ asn1_NOVALUE,
+ [{serviceChangeReply,
+ {'ServiceChangeReply',
+ [{megaco_term_id,false,["root"]}],
+ {serviceChangeResParms,
+ {'ServiceChangeResParm',{...}|...}}}}]}]}}},
+ {{deviceName,"gateway_ub"},
+ {1,
+ {ok,[{'ActionReply',0,
+ asn1_NOVALUE,
+ asn1_NOVALUE,
+ [{serviceChangeReply,
+ {'ServiceChangeReply',
+ [{megaco_term_id,false,["root"]}],
+ {serviceChangeResParms,
+ {'ServiceChangeResParm'|...}}}}]}]}}}]
+ (mg@amrod)5>
+ </code>
+ <p>The Megaco adopted viewer looks like this, when we have clicked
+ on the "gateway_tt" actor name in order to only display the events
+ regarding that actor:</p>
+ <p></p>
+ <image file="megaco_tracer.gif">
+ <icaption>The viewer adopted for Megaco</icaption>
+ </image>
+ <p>A pretty printed Megaco message looks like this:</p>
+ <p></p>
+ <image file="megaco_filter.gif">
+ <icaption>A textual Megaco message</icaption>
+ </image>
+ <p>And the corresponding internal form for the same Megaco message
+ looks like this:</p>
+ <p></p>
+ <image file="megaco_collector.gif">
+ <icaption>The internal form of a Megaco message</icaption>
+ </image>
+ </section>
+</chapter>
+