From f74f4c8b5f65b1cd75b2dc91b94666fa65a9032a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 26 May 2016 17:44:52 +0200 Subject: runtime_tools: Document a lttng usage example --- lib/runtime_tools/doc/src/LTTng.xml | 144 +++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 4 deletions(-) (limited to 'lib/runtime_tools') 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 parent : string :: Process ID. Ex. "<0.131.0>" entry : string :: Code Location. Ex. "lists:sort/1" +

+ Available through + erlang:trace/3 with trace flag procs and {tracer,dyntrace,[]} as tracer module. +

Example:

process_spawn: { cpu_id = 3 }, { pid = "<0.131.0>", parent = "<0.130.0>", entry = "erlang:apply/2" } @@ -84,6 +88,10 @@ $ make from : string :: Process ID or Port ID. Ex. "<0.131.0>" type : string :: "link" | "unlink" +

+ Available through + erlang:trace/3 with trace flag procs and {tracer,dyntrace,[]} as tracer module. +

Example:

process_link: { cpu_id = 3 }, { from = "<0.130.0>", to = "<0.131.0>", type = "link" } @@ -93,6 +101,10 @@ $ make pid : string :: Process ID. Ex. "<0.131.0>" reason : string :: Exit reason. Ex. "normal" +

+ Available through + erlang:trace/3 with trace flag procs and {tracer,dyntrace,[]} as tracer module. +

Example:

process_exit: { cpu_id = 3 }, { pid = "<0.130.0>", reason = "normal" } @@ -111,7 +123,10 @@ $ make entry : string :: Code Location. Ex. "lists:sort/1" type : string :: "in" | "out" | "in_exiting" | "out_exiting" | "out_exited" - +

+ Available through + erlang:trace/3 with trace flag running and {tracer,dyntrace,[]} as tracer module. +

Example:

process_scheduled: { cpu_id = 0 }, { pid = "<0.136.0>", entry = "erlang:apply/2", type = "in" } @@ -122,7 +137,10 @@ $ make driver : string :: Driver name. Ex. "efile" port : string :: Port ID. Ex. "#Port<0.1031>" - +

+ Available through + erlang:trace/3 with trace flag ports and {tracer,dyntrace,[]} as tracer module. +

Example:

port_open: { cpu_id = 5 }, { pid = "<0.131.0>", driver = "'/bin/sh -s unix:cmd'", port = "#Port<0.1887>" } @@ -131,6 +149,10 @@ $ make port : string :: Port ID. Ex. "#Port<0.1031>" reason : string :: Exit reason. Ex. "normal" +

+ Available through + erlang:trace/3 with trace flag ports and {tracer,dyntrace,[]} as tracer module. +

Example:

port_exit: { cpu_id = 5 }, { port = "#Port<0.1887>", reason = "normal" } @@ -140,10 +162,18 @@ $ make from : string :: Process ID. Ex. "<0.131.0>" type : string :: "link" | "unlink" +

+ Available through + erlang:trace/3 with trace flag ports and {tracer,dyntrace,[]} as tracer module. +

Example:

port_link: { cpu_id = 5 }, { from = "#Port<0.1887>", to = "<0.131.0>", type = "unlink" }

port_scheduled

+

+ Available through + erlang:trace/3 with trace flag running and {tracer,dyntrace,[]} as tracer module. +

port : string :: Port ID. Ex. "#Port<0.1031>" entry : string :: Callback. Ex. "open" @@ -152,13 +182,20 @@ $ make

Example:

port_scheduled: { cpu_id = 5 }, { pid = "#Port<0.1905>", entry = "close", type = "out" } - +

+ Available through + erlang:trace/3 with trace flag running and {tracer,dyntrace,[]} as tracer module. +

function_call

pid : string :: Process ID. Ex. "<0.131.0>" entry : string :: Code Location. Ex. "lists:sort/1" depth : integer :: Stack depth. Ex. 0 +

+ Available through + erlang:trace/3 with trace flag call and {tracer,dyntrace,[]} as tracer module. +

Example:

function_call: { cpu_id = 5 }, { pid = "<0.145.0>", entry = "dyntrace_lttng_SUITE:'-t_call/1-fun-1-'/0", depth = 0 } @@ -168,6 +205,10 @@ $ make entry : string :: Code Location. Ex. "lists:sort/1" depth : integer :: Stack depth. Ex. 0 +

+ Available through + erlang:trace/3 with trace flag call or return_to and {tracer,dyntrace,[]} as tracer module. +

Example:

function_return: { cpu_id = 5 }, { pid = "<0.145.0>", entry = "dyntrace_lttng_SUITE:waiter/0", depth = 0 } @@ -177,6 +218,10 @@ $ make entry : string :: Code Location. Ex. "lists:sort/1" class : string :: Error reason. Ex. "error" +

+ Available through + erlang:trace/3 with trace flag call and {tracer,dyntrace,[]} as tracer module. +

Example:

function_exception: { cpu_id = 5 }, { pid = "<0.144.0>", entry = "t:call_exc/1", class = "error" } @@ -186,6 +231,10 @@ $ make to : string :: Process ID or Port ID. Ex. "<0.131.0>" message : string :: Message sent. Ex. "{<0.162.0>,ok}" +

+ Available through + erlang:trace/3 with trace flag send and {tracer,dyntrace,[]} as tracer module. +

Example:

message_send: { cpu_id = 3 }, { from = "#Port<0.1938>", to = "<0.160.0>", message = "{#Port<0.1938>,eof}" } @@ -194,6 +243,10 @@ $ make to : string :: Process ID or Port ID. Ex. "<0.131.0>" message : string :: Message received. Ex. "{<0.162.0>,ok}" +

+ Available through + erlang:trace/3 with trace flag 'receive' and {tracer,dyntrace,[]} as tracer module. +

Example:

message_receive: { cpu_id = 7 }, { to = "<0.167.0>", message = "{<0.165.0>,ok}" } @@ -204,6 +257,10 @@ $ make heap : integer :: Young heap word size. Ex. 233 old_heap : integer :: Old heap word size. Ex. 233 +

+ Available through + erlang:trace/3 with trace flag garbage_collection and {tracer,dyntrace,[]} as tracer module. +

Example:

gc_minor_start: { cpu_id = 0 }, { pid = "<0.172.0>", need = 0, heap = 610, old_heap = 0 } @@ -214,6 +271,10 @@ $ make heap : integer :: Young heap word size. Ex. 233 old_heap : integer :: Old heap word size. Ex. 233 +

+ Available through + erlang:trace/3 with trace flag garbage_collection and {tracer,dyntrace,[]} as tracer module. +

Example:

gc_minor_end: { cpu_id = 0 }, { pid = "<0.172.0>", reclaimed = 120, heap = 1598, old_heap = 1598 } @@ -224,6 +285,10 @@ $ make heap : integer :: Young heap word size. Ex. 233 old_heap : integer :: Old heap word size. Ex. 233 +

+ Available through + erlang:trace/3 with trace flag garbage_collection and {tracer,dyntrace,[]} as tracer module. +

Example:

gc_major_start: { cpu_id = 0 }, { pid = "<0.172.0>", need = 8, heap = 2586, old_heap = 1598 } @@ -234,6 +299,10 @@ $ make heap : integer :: Young heap word size. Ex. 233 old_heap : integer :: Old heap word size. Ex. 233 +

+ Available through + erlang:trace/3 with trace flag garbage_collection and {tracer,dyntrace,[]} as tracer module. +

Example:

gc_major_end: { cpu_id = 0 }, { pid = "<0.172.0>", reclaimed = 240, heap = 4185, old_heap = 0 } @@ -454,6 +523,73 @@ $ make
- Examples + Example of process tracing +

An example of process tracing of os_mon and friends.

+ +

Clean start of lttng in a bash shell.

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

Start an Erlang node with lttng enabled.

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

Load the dyntrace module.

+ + 
1> l(dyntrace).
+{module,dyntrace}
+ +

All tracepoints via dyntrace are now visibile and can be listed through lttng list -u.

+ +

Enable the process_register LTTng tracepoint for Erlang.

+ + 
$ lttng enable-event -u com_ericsson_dyntrace:process_register
+UST event com_ericsson_dyntrace:process_register created in channel channel0
+ +

Enable process tracing for new processes and use dyntrace as tracer backend.

+ + 
2> erlang:trace(new,true,[procs,{tracer,dyntrace,[]}]).
+0
+ +

Start LTTng tracing.

+ + 
$ lttng start
+Tracing started for session erlang-demo
+ +

Start the os_mon application in Erlang.

+ + 
3> application:ensure_all_started(os_mon).
+{ok,[sasl,os_mon]}
+ +

Stop LTTng tracing and view the result.

+ + 
$ 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" }
-- cgit v1.2.3