diff options
Diffstat (limited to 'lib/et/doc/src/et_examples.xml')
| -rw-r--r-- | lib/et/doc/src/et_examples.xml | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/lib/et/doc/src/et_examples.xml b/lib/et/doc/src/et_examples.xml deleted file mode 100644 index 7627b191a1..0000000000 --- a/lib/et/doc/src/et_examples.xml +++ /dev/null @@ -1,311 +0,0 @@ -<?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åkan Mattsson</prepared> - <responsible>Håkan Mattsson</responsible> - <docno></docno> - <approved>Hå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> - |