From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/et/doc/src/et_examples.xml | 311 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100644 lib/et/doc/src/et_examples.xml (limited to 'lib/et/doc/src/et_examples.xml') 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 @@ + + + + +
+ + 20022009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Examples + Håkan Mattsson + Håkan Mattsson + + Håkan Mattsson + + + %VSN% + et_examples.xml +
+ +
+ A simulated Mnesia transaction +

The Erlang code for running the simulated Mnesia transaction example + in the previous chapter is included in the et/examples/et_demo.erl file: +

+

+ +

+ +

If you invoke the et_demo:sim_trans() 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:

+

+ + mnesia:transaction(fun() -> mnesia:write({my_tab, key, val}) end). + +

And the viewer window will look like:

+

+ et_demo:sim_trans(). + {ok,{table_handle,<0.30.0>,11,trace_ts,#Fun}} + 2> + ]]> +

+ + A simulated Mnesia transaction which writes one record + +
+ +
+ Some convenient functions used in the Mnesia transaction example +

The module_as_actor 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 + [{message, {caller}}, {return_trace}] options to dbg:tpl/2 + function will imply the necessary information in the Erlang traces. + Here follows the module_as_actor filter:

+

+ +

The plain_process_info filter does not alter the event-records. + It merely ensures that the event not related to processes are skipped:

+

+ +

The plain_process_info_nolink filter does not alter the + event-records. It do makes use of the plain_process_info , but + do also ensure that the process info related to linking and unlinking + is skipped:

+

+ +

In order to simplify the startup of an et_viewer process + with the filters mentioned above, plus some others (that also are + found in et/examples/et_demo.erl src/et_collector.erl the + et_demo:start/0,1 functions can be used:

+

+ +

A simple one-liner starts the tool:

+ + erl -pa ../examples -s et_demo + +

The filters are included by the following parameters:

+

+ +
+ +
+ Erlang trace of a Mnesia transaction +

The following piece of code et_demo:trace_mnesia/0 + 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 + whereis/1 call in the following code requires that both the + traced Mnesia application and the et_vieweris running on the + same node:

+

+ +

The et_demo:live_trans/0 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:

+

+ +

Now we run the et_demo:live_trans/0 function:

+

+ + erl -pa ../examples -s et_demo live_trans + Erlang (BEAM) emulator version 2002.10.08 [source] + + Eshell V2002.10.08 (abort with ^G) + 1> + +

Please, explore the different filters in order to see how the traced + transaction can be seen from different point of views:

+

+ + A real Mnesia transaction which writes one record + +
+ +
+ Erlang trace of Megaco startup +

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.

+

In the Megaco application of Erlang/OTP, the code is carefully + instrumented with calls to et:report_event/5. For call a detail + level is set in order to dynamically control the trace level in a + simple manner.

+

The megaco_filter module implements a customized filter + for Megaco messages. It does also make use of trace_global + combined with usage of the trace_pattern:

+

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

First we start an Erlang node with the a global collector and + its viewer. The et_viewer: search for: [] ++ ["gateway_tt"] + 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.

+

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

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:

+

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

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:

+

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

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:

+

+ + The viewer adopted for Megaco + +

A pretty printed Megaco message looks like this:

+

+ + A textual Megaco message + +

And the corresponding internal form for the same Megaco message + looks like this:

+

+ + The internal form of a Megaco message + +
+ + -- cgit v1.2.3