diff options
Diffstat (limited to 'lib/runtime_tools/doc/src')
| -rw-r--r-- | lib/runtime_tools/doc/src/LTTng.xml | 144 | ||||
| -rw-r--r-- | lib/runtime_tools/doc/src/dbg.xml | 64 |
2 files changed, 202 insertions, 6 deletions
diff --git a/lib/runtime_tools/doc/src/LTTng.xml b/lib/runtime_tools/doc/src/LTTng.xml index 06152c66d6..9b490a27a0 100644 --- a/lib/runtime_tools/doc/src/LTTng.xml +++ b/lib/runtime_tools/doc/src/LTTng.xml @@ -75,6 +75,10 @@ $ make </code> <item><c>parent : string</c> :: Process ID. Ex. <c>"<0.131.0>"</c></item> <item><c>entry : string</c> :: Code Location. Ex. <c>"lists:sort/1"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>procs</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">process_spawn: { cpu_id = 3 }, { pid = "<0.131.0>", parent = "<0.130.0>", entry = "erlang:apply/2" }</code> @@ -84,6 +88,10 @@ $ make </code> <item><c>from : string</c> :: Process ID or Port ID. Ex. <c>"<0.131.0>"</c></item> <item><c>type : string</c> :: <c>"link" | "unlink"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>procs</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">process_link: { cpu_id = 3 }, { from = "<0.130.0>", to = "<0.131.0>", type = "link" }</code> @@ -93,6 +101,10 @@ $ make </code> <item><c>pid : string</c> :: Process ID. Ex. <c>"<0.131.0>"</c></item> <item><c>reason : string</c> :: Exit reason. Ex. <c>"normal"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>procs</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">process_exit: { cpu_id = 3 }, { pid = "<0.130.0>", reason = "normal" }</code> @@ -111,7 +123,10 @@ $ make </code> <item><c>entry : string</c> :: Code Location. Ex. <c>"lists:sort/1"</c></item> <item><c>type : string</c> :: <c>"in" | "out" | "in_exiting" | "out_exiting" | "out_exited"</c></item> </list> - + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>running</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">process_scheduled: { cpu_id = 0 }, { pid = "<0.136.0>", entry = "erlang:apply/2", type = "in" }</code> @@ -122,7 +137,10 @@ $ make </code> <item><c>driver : string</c> :: Driver name. Ex. <c>"efile"</c></item> <item><c>port : string</c> :: Port ID. Ex. <c>"#Port<0.1031>"</c></item> </list> - + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>ports</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">port_open: { cpu_id = 5 }, { pid = "<0.131.0>", driver = "'/bin/sh -s unix:cmd'", port = "#Port<0.1887>" }</code> @@ -131,6 +149,10 @@ $ make </code> <item><c>port : string</c> :: Port ID. Ex. <c>"#Port<0.1031>"</c></item> <item><c>reason : string</c> :: Exit reason. Ex. <c>"normal"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>ports</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">port_exit: { cpu_id = 5 }, { port = "#Port<0.1887>", reason = "normal" }</code> @@ -140,10 +162,18 @@ $ make </code> <item><c>from : string</c> :: Process ID. Ex. <c>"<0.131.0>"</c></item> <item><c>type : string</c> :: <c>"link" | "unlink"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>ports</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">port_link: { cpu_id = 5 }, { from = "#Port<0.1887>", to = "<0.131.0>", type = "unlink" }</code> <p><em>port_scheduled</em></p> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>running</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <list type="bulleted"> <item><c>port : string</c> :: Port ID. Ex. <c>"#Port<0.1031>"</c></item> <item><c>entry : string</c> :: Callback. Ex. <c>"open"</c></item> @@ -152,13 +182,20 @@ $ make </code> <p>Example:</p> <code type="none">port_scheduled: { cpu_id = 5 }, { pid = "#Port<0.1905>", entry = "close", type = "out" }</code> - + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>running</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p><em>function_call</em></p> <list type="bulleted"> <item><c>pid : string</c> :: Process ID. Ex. <c>"<0.131.0>"</c></item> <item><c>entry : string</c> :: Code Location. Ex. <c>"lists:sort/1"</c></item> <item><c>depth : integer</c> :: Stack depth. Ex. <c>0</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>call</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">function_call: { cpu_id = 5 }, { pid = "<0.145.0>", entry = "dyntrace_lttng_SUITE:'-t_call/1-fun-1-'/0", depth = 0 }</code> @@ -168,6 +205,10 @@ $ make </code> <item><c>entry : string</c> :: Code Location. Ex. <c>"lists:sort/1"</c></item> <item><c>depth : integer</c> :: Stack depth. Ex. <c>0</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>call</c> or <c>return_to</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">function_return: { cpu_id = 5 }, { pid = "<0.145.0>", entry = "dyntrace_lttng_SUITE:waiter/0", depth = 0 }</code> @@ -177,6 +218,10 @@ $ make </code> <item><c>entry : string</c> :: Code Location. Ex. <c>"lists:sort/1"</c></item> <item><c>class : string</c> :: Error reason. Ex. <c>"error"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>call</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">function_exception: { cpu_id = 5 }, { pid = "<0.144.0>", entry = "t:call_exc/1", class = "error" }</code> @@ -186,6 +231,10 @@ $ make </code> <item><c>to : string</c> :: Process ID or Port ID. Ex. <c>"<0.131.0>"</c></item> <item><c>message : string</c> :: Message sent. Ex. <c>"{<0.162.0>,ok}"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>send</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">message_send: { cpu_id = 3 }, { from = "#Port<0.1938>", to = "<0.160.0>", message = "{#Port<0.1938>,eof}" }</code> @@ -194,6 +243,10 @@ $ make </code> <item><c>to : string</c> :: Process ID or Port ID. Ex. <c>"<0.131.0>"</c></item> <item><c>message : string</c> :: Message received. Ex. <c>"{<0.162.0>,ok}"</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>'receive'</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">message_receive: { cpu_id = 7 }, { to = "<0.167.0>", message = "{<0.165.0>,ok}" }</code> @@ -204,6 +257,10 @@ $ make </code> <item><c>heap : integer</c> :: Young heap word size. Ex. <c>233</c></item> <item><c>old_heap : integer</c> :: Old heap word size. Ex. <c>233</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>garbage_collection</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">gc_minor_start: { cpu_id = 0 }, { pid = "<0.172.0>", need = 0, heap = 610, old_heap = 0 }</code> @@ -214,6 +271,10 @@ $ make </code> <item><c>heap : integer</c> :: Young heap word size. Ex. <c>233</c></item> <item><c>old_heap : integer</c> :: Old heap word size. Ex. <c>233</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>garbage_collection</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">gc_minor_end: { cpu_id = 0 }, { pid = "<0.172.0>", reclaimed = 120, heap = 1598, old_heap = 1598 }</code> @@ -224,6 +285,10 @@ $ make </code> <item><c>heap : integer</c> :: Young heap word size. Ex. <c>233</c></item> <item><c>old_heap : integer</c> :: Old heap word size. Ex. <c>233</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>garbage_collection</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">gc_major_start: { cpu_id = 0 }, { pid = "<0.172.0>", need = 8, heap = 2586, old_heap = 1598 }</code> @@ -234,6 +299,10 @@ $ make </code> <item><c>heap : integer</c> :: Young heap word size. Ex. <c>233</c></item> <item><c>old_heap : integer</c> :: Old heap word size. Ex. <c>233</c></item> </list> + <p> + Available through + <seealso marker="erts:erlang#trace-3"><c>erlang:trace/3</c></seealso> with trace flag <c>garbage_collection</c> and <c>{tracer,dyntrace,[]}</c> as tracer module. + </p> <p>Example:</p> <code type="none">gc_major_end: { cpu_id = 0 }, { pid = "<0.172.0>", reclaimed = 240, heap = 4185, old_heap = 0 }</code> @@ -454,6 +523,73 @@ $ make </code> </section> <section> - <title>Examples</title> + <title>Example of process tracing</title> + <p>An example of process tracing of <c>os_mon</c> and friends.</p> + + <p>Clean start of lttng in a bash shell.</p> + + <pre>$ lttng create erlang-demo +Spawning a session daemon +Session erlang-demo created. +Traces will be written in /home/egil/lttng-traces/erlang-demo-20160526-165920</pre> + + <p>Start an Erlang node with lttng enabled.</p> + + <pre>$ erl +Erlang/OTP 19 [erts-8.0] [source-4d7b24d] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false] [lttng] + +Eshell V8.0 (abort with ^G) +1></pre> + + <p>Load the <c>dyntrace</c> module.</p> + + <pre>1> <input>l(dyntrace).</input> +{module,dyntrace}</pre> + + <p>All tracepoints via dyntrace are now visibile and can be listed through <c>lttng list -u</c>.</p> + + <p>Enable the process_register LTTng tracepoint for Erlang.</p> + + <pre>$ lttng enable-event -u com_ericsson_dyntrace:process_register +UST event com_ericsson_dyntrace:process_register created in channel channel0</pre> + + <p>Enable process tracing for new processes and use <c>dyntrace</c> as tracer backend.</p> + + <pre>2> <input>erlang:trace(new,true,[procs,{tracer,dyntrace,[]}]).</input> +0</pre> + + <p>Start LTTng tracing.</p> + + <pre>$ lttng start +Tracing started for session erlang-demo</pre> + + <p>Start the <c>os_mon</c> application in Erlang.</p> + + <pre>3> <input>application:ensure_all_started(os_mon).</input> +{ok,[sasl,os_mon]}</pre> + + <p>Stop LTTng tracing and view the result.</p> + + <pre>$ lttng stop +Tracing stopped for session erlang-demo +$ lttng view +[17:20:42.561168759] (+?.?????????) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.66.0>", name = "sasl_sup", type = "register" } +[17:20:42.561215519] (+0.000046760) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.67.0>", name = "sasl_safe_sup", type = "register" } +[17:20:42.562149024] (+0.000933505) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.68.0>", name = "alarm_handler", type = "register" } +[17:20:42.571035803] (+0.008886779) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.69.0>", name = "release_handler", type = "register" } +[17:20:42.574939868] (+0.003904065) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.74.0>", name = "os_mon_sup", type = "register" } +[17:20:42.576818712] (+0.001878844) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.75.0>", name = "disksup", type = "register" } +[17:20:42.580032013] (+0.003213301) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.76.0>", name = "memsup", type = "register" } +[17:20:42.583046339] (+0.003014326) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.78.0>", name = "cpu_sup", type = "register" } +[17:20:42.586206242] (+0.003159903) elxd1168lx9 com_ericsson_dyntrace:process_register: \ + { cpu_id = 5 }, { pid = "<0.82.0>", name = "timer_server", type = "register" }</pre> </section> </chapter> diff --git a/lib/runtime_tools/doc/src/dbg.xml b/lib/runtime_tools/doc/src/dbg.xml index 103b8b52e9..14a81b2293 100644 --- a/lib/runtime_tools/doc/src/dbg.xml +++ b/lib/runtime_tools/doc/src/dbg.xml @@ -189,9 +189,9 @@ Error: fun containing local erlang function calls ('is_atomm' called in guard)\ <tag><c>all</c></tag> <item>All processes and ports in the system as well as all processes and ports created hereafter are to be traced.</item> - <tag><c>all_processes</c></tag> + <tag><c>processes</c></tag> <item>All processes in the system as well as all processes created hereafter are to be traced.</item> - <tag><c>all_ports</c></tag> + <tag><c>ports</c></tag> <item>All ports in the system as well as all ports created hereafter are to be traced.</item> <tag><c>new</c></tag> <item>All processes and ports created after the call is are to be traced.</item> @@ -439,6 +439,50 @@ Error: fun containing local erlang function calls ('is_atomm' called in guard)\ global calls (and functions).</p> </desc> </func> + + + <func> + <name>tpe(Event, MatchSpec) -> {ok, MatchDesc} | {error, term()}</name> + <fsummary>Set pattern for traced event</fsummary> + <type> + <v>Event = send | 'receive'</v> + <v>MatchSpec = integer() | Built-inAlias | [] | match_spec()</v> + <v>Built-inAlias = x | c | cx</v> + <v>MatchDesc = [MatchInfo]</v> + <v>MatchInfo = {saved, integer()} | MatchNum</v> + <v>MatchNum = {matched, node(), 1} | {matched, node(), 0, RPCError}</v> + </type> + <desc> + <p>This function associates a match specification with trace event + <c>send</c> or <c>'receive'</c>. By default all executed <c>send</c> + and <c>'receive'</c> events are traced if enabled for a process. + A match specification can be used to filter traced events + based on sender, receiver and/or message content.</p> + <p>For a description of the <c>match_spec()</c> syntax, + please turn to the <em>User's guide</em> part of the online + documentation for the runtime system (<em>erts</em>). The + chapter <seealso marker="erts:match_spec"><em>Match Specifications in Erlang</em></seealso> + explains the general match specification "language".</p> + <p>For <c>send</c>, the matching is done on the list <c>[Receiver, Msg]</c>. + <c>Receiver</c> is the process or port identity of the receiver and + <c>Msg</c> is the message term. The pid of the sending process can be + accessed with the guard function <c>self/0</c>.</p> + <p>For <c>'receive'</c>, the matching is done on the list <c>[Node, Sender, Msg]</c>. + <c>Node</c> is the node name of the sender. <c>Sender</c> is the + process or port identity of the sender, or the atom + <c>undefined</c> if the sender is not known (which may + be the case for remote senders). <c>Msg</c> is the + message term. The pid of the receiving process can be + accessed with the guard function <c>self/0</c>.</p> + <p>All nodes added with <seealso marker="#n-1"><c>n/1</c></seealso> or + <seealso marker="#tracer-3"><c>tracer/3</c></seealso> will + be affected by this call.</p> + <p>The return value is the same as for + <seealso marker="#tp-2"><c>tp/2</c></seealso>. The number of matched + events are never larger than 1 as <c>tpe/2</c> does not + accept any form of wildcards for argument <c>Event</c>.</p> + </desc> + </func> <func> <name>ctp()</name> <fsummary>Clear call trace pattern for the specified functions</fsummary> @@ -563,6 +607,22 @@ Error: fun containing local erlang function calls ('is_atomm' called in guard)\ </desc> </func> <func> + <name>ctpe(Event) -> {ok, MatchDesc} | {error, term()}</name> + <fsummary>Clear trace pattern for the specified event</fsummary> + <type> + <v>Event = send | 'receive'</v> + <v>MatchDesc = [MatchNum]</v> + <v>MatchNum = {matched, node(), 1} | {matched, node(), 0, RPCError}</v> + </type> + <desc> + <p>This function clears match specifications for the specified + trace event (<c>send</c> or <c>'receive'</c>). It will revert back + to the default behavior of tracing all triggered events.</p> + <p>The return value follow the same style as for + <seealso marker="#ctp-1"><c>ctp/1</c></seealso>.</p> + </desc> + </func> + <func> <name>ltp() -> ok</name> <fsummary>List saved and built-in match specifications on the console.</fsummary> <desc> |