Runtime_Tools Copyright © 1999-2018 Ericsson AB. All Rights Reserved. Runtime_Tools 1.13 July 2, 2018 Copyright © 1999-2018 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Ericsson AB. All Rights Reserved.. July 2, 2018 Ericsson AB. All Rights Reserved.: Runtime_Tools | 1 1.1 LTTng and Erlang/OTP 1 Runtime Tools User's Guide Runtime Tools 1.1 LTTng and Erlang/OTP 1.1.1 Introduction The Linux Trace Toolkit: next generation is an open source system software package for correlated tracing of the Linux kernel, user applications and libraries. For more information, please visit http://lttng.org 1.1.2 Building Erlang/OTP with LTTng support Configure and build Erlang with LTTng support: For LTTng to work properly with Erlang/OTP you need the following packages installed: • LTTng-tools: a command line interface to control tracing sessions. • LTTng-UST: user space tracing library. On Ubuntu this can be installed via aptitude: $ sudo aptitude install lttng-tools liblttng-ust-dev See Installing LTTng for more information on how to install LTTng on your system. After LTTng is properly installed on the system Erlang/OTP can be built with LTTng support. $ ./configure --with-dynamic-trace=lttng $ make 1.1.3 Dyntrace Tracepoints All tracepoints are in the domain of org_erlang_dyntrace All Erlang types are the string equivalent in LTTng. process_spawn • pid : string :: Process ID. Ex. "<0.131.0>" • 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" } process_link • to : string :: Process ID or Port ID. Ex. "<0.131.0>" • from : string :: Process ID or Port ID. Ex. "<0.131.0>" 2 | Ericsson AB. All Rights Reserved.: Runtime_Tools 1.1 LTTng and Erlang/OTP • 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" } process_exit • 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" } process_register • pid : string :: Process ID. Ex. "<0.131.0>" • name : string :: Registered name. Ex. "logger" • type : string :: "register" | "unregister" Example: process_register: { cpu_id = 0 }, { pid = "<0.128.0>", name = "dyntrace_lttng_SUITE" type = "register" } process_scheduled • pid : string :: Process ID. Ex. "<0.131.0>" • 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" } port_open • pid : string :: Process ID. Ex. "<0.131.0>" • driver : string :: Driver name. Ex. "tcp_inet" • 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>" } port_exit • 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" } Ericsson AB. All Rights Reserved.: Runtime_Tools | 3 1.1 LTTng and Erlang/OTP port_link • to : string :: Process ID. Ex. "<0.131.0>" • 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" • type : string :: "in" | "out" | "in_exiting" | "out_exiting" | "out_exited" 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 } function_return • 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 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 } function_exception • pid : string :: Process ID. Ex. "<0.131.0>" • 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" } 4 | Ericsson AB. All Rights Reserved.: Runtime_Tools 1.1 LTTng and Erlang/OTP message_send • from : string :: Process ID or Port ID. Ex. "<0.131.0>" • 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}" } message_receive • 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}" } gc_minor_start • pid : string :: Process ID. Ex. "<0.131.0>" • need : integer :: Heap need. Ex. 2 • 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 } gc_minor_end • pid : string :: Process ID. Ex. "<0.131.0>" • reclaimed : integer :: Heap reclaimed. Ex. 2 • 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 } gc_major_start • pid : string :: Process ID. Ex. "<0.131.0>" • need : integer :: Heap need. Ex. 2 • heap : integer :: Young heap word size. Ex. 233 • old_heap : integer :: Old heap word size. Ex. 233 Ericsson AB. All Rights Reserved.: Runtime_Tools | 5 1.1 LTTng and Erlang/OTP 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 } gc_major_end • pid : string :: Process ID. Ex. "<0.131.0>" • reclaimed : integer :: Heap reclaimed. Ex. 2 • 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 } 1.1.4 BEAM Tracepoints All tracepoints are in the domain of org_erlang_otp All Erlang types are the string equivalent in LTTng. scheduler_poll • scheduler : integer :: Scheduler ID. Ex. 1 • runnable : integer :: Runnable. Ex. 1 Example: scheduler_poll: { cpu_id = 4 }, { scheduler = 1, runnable = 1 } driver_init • driver : string :: Driver name. Ex. "tcp_inet" • major : integer :: Major version. Ex. 3 • minor : integer :: Minor version. Ex. 1 • flags : integer :: Flags. Ex. 1 Example: driver_init: { cpu_id = 2 }, { driver = "caller_drv", major = 3, minor = 3, flags = 1 } driver_start • pid : string :: Process ID. Ex. "<0.131.0>" • driver : string :: Driver name. Ex. "tcp_inet" • port : string :: Port ID. Ex. "#Port<0.1031>" Example: driver_start: { cpu_id