The R13B03 release.OTP_R13B03

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>
+