Copyright © 2004-2020 mats cronqvist
Version: 2.0.6
Authors: mats cronqvist {github.com/massemanet}.
redbug is a tool to interact with the Erlang trace facility. It will instruct the Erlang VM to generate so-called 'trace messages' when certain events (such as a particular function being called) occur. It uses a safe subset of the tracing functionality, and exits if it feels overloaded, e.g. if it gets flooded by trace messages. It runs in the background, collecting trace messages, until it reaches one of its termination criteria (number of messages/file size or elapsed time).
The trace messages are either printed (i.e. human readable) to a file or to the screen; or written to a trc file. Using a trc file puts less stress on the system, but there is no way to count the messages (so the 'msgs' opt is ignored), and the files can only be read by special tools (such as 'bread'). Printing and trc files cannot be combined. By default (i.e. if the 'file' opt is not given), messages are printed.
Records are not like the other Erlang collection types (lists, maps, and tuples) in that they are a compile time construct (they are turned into tuples before compilation).
Hence, record names are not globally unique, but are unique per module. redbug deals with this by allowing the syntax "module#record" to specify a record. E.g. likeredbug:start("m:f(m#rec{a = b})").
In order to print record field names in return values on has to tell
redbug in which modules to look for records. Use the {records,
[Module]}
option.
dtop gives a per-process view of the system. It is simpilar to top
in that it pronts a screenful of info every N (default 2) seconds.
Each screenful consists of a header and a line pre process.
------------------------------------------------------------------------------- nonode@nohost size: 22.3M(2.6G), cpu%: 2(13), procs: 71, runq: 0, 18:21:19 memory: proc 5.9M, atom 442.6k, bin 1.0M, code 7.4M, ets 794.4k pid name current msgq mem cpu <0.10.0> erl_prim_loader erl_prim_loader:l 0 1.1M 1 <0.194.0> redbug_dtop redbug_dtop:prc_i 0 111.6k 1 <0.50.0> code_server code_server:loop/ 0 176.3k 0
By default, the printer function writes a header line that looks like this;
% 18:38:50 <0.188.0>({erlang,apply,2})
A timestamp, the pid, and the process name; the registered name if it exists, otherwise the inti function of the process.
A function call is printed like this;
% erlang:demonitor(#Ref<0.2419348116.2832203778.13012>)
and a return from a funtion like this;
% erlang:demonitor/1 -> true
i.e. module:function/arity -> return value
Basic call trace
1> redbug:start("erlang:demonitor"). {75,2} % 18:27:21 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203778.12948>) % 18:27:21 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203777.10938>, [flush]) % 18:27:21 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203777.10939>, [flush]) % 18:27:21 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203777.10940>, [flush]) redbug done, timeout - 4
As above, print return value. The return value is a separate message.
2> redbug:start("erlang:demonitor->return",[{msgs,2}]). {75,2} % 18:31:15 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203780.10535>) % 18:31:15 <0.188.0>({erlang,apply,2}) % erlang:demonitor/1 -> true redbug done, msg_count - 1
As above, also print the call stack. Note that not all functions in the call chain are on the stack, only functions we will return to (this is a consequence of tail call optimization.)
4> redbug:start("erlang:demonitor->return,stack",[{msgs,2}]). {75,2} % 18:32:54 <0.188.0>({erlang,apply,2}) % erlang:demonitor(#Ref<0.2419348116.2832203778.13012>) % redbug:block_a_little/0 % redbug:start/2 % erl_eval:do_apply/6 % shell:exprs/7 % shell:eval_exprs/7 % shell:eval_loop/3 % 18:32:54 <0.188.0>({erlang,apply,2}) % erlang:demonitor/1 -> true redbug done, msg_count - 1
Trace on messages that the shell process receives.
5> redbug:start('receive',[{procs,[self()]}]). {1,0} % 18:35:16 <0.188.0>({erlang,apply,2}) % <<< {running,1,0} % 18:35:16 <0.188.0>({erlang,apply,2}) % <<< {io_reply,#Ref<0.2419348116.2832203778.13028>,150} % 18:35:16 <0.188.0>({erlang,apply,2}) % <<< {io_reply,#Ref<0.2419348116.2832203778.13029>, [{expand_fun,#Fun<group.0.90280613>}, {echo,true}, {binary,false}, {encoding,unicode}]} % 18:35:16 <0.188.0>({erlang,apply,2}) % <<< {io_reply,#Ref<0.2419348116.2832203778.13030>,ok}
As above, but also trace on sends from the shell process. note that in this case the 'print_pid' opt would hide that there is a send to the group server.
7> redbug:start([send,'receive'],[{procs,[self()]}]). {1,0} % 18:36:25 <0.188.0>({erlang,apply,2}) % <<< {running,1,0} % 18:36:25 <0.188.0>({erlang,apply,2}) % <0.186.0>({group,server,3}) <<< {io_request,<0.188.0>, #Ref<0.2419348116.2832203777.10998>, {get_geometry,columns}} redbug done, timeout - 2
Call trace with a function head match. Note that the first call to ets:tab2list/1 does not trigger the tracer.
8> redbug:start("ets:tab2list(inet_db)",[{msgs,2},print_pid]). {30,1} 9> ets:tab2list(ac_tab),ok. ok 10> ets:tab2list(inet_db),ok. ok % 18:38:50 <0.188.0>({erlang,apply,2}) % ets:tab2list(inet_db) redbug done, timeout - 1
As above, but use the 'blocking' opt. redbug:start/2 blocks until end of trace, and returns the stop reason and a list of trace messages.
11> spawn(fun()->receive after 2000->ets:tab2list(inet_db) end end),redbug:start("ets:tab2list(inet_db)",[blocking,{time,3000}]). {timeout,[{call,{{ets,tab2list,[inet_db]},<<>>}, {<0.273.0>,dead}, {18,42,17,555959}}]}
Read record definition from file
12> redbug:start("file:read_file_info->return",#{records=>[file]}), file:read_file_info("/"). % 14:43:06 <0.205.0>({erlang,apply,2}) % file:read_file_info("/") % 14:43:06 <0.205.0>({erlang,apply,2}) % file:read_file_info/1 -> {ok,{file_info, [{size,4096}, {type,directory}, {access,read}, {atime,{{2020,3,28},{11,51,5}}}, {mtime,{{2020,2,2},{11,42,36}}}, {ctime,{{2020,2,2},{11,42,36}}}, {mode,16877}, {links,22}, {major_device,64769}, {minor_device,0}, {inode,2}, {uid,0}, {gid,0}]}} redbug done, timeout - 1
Use the module#record
syntax to specify a match.
13> redbug:start("erlang:tuple_size(file#file_info{size = 666})->return",[arity]). 14> rr(file),tuple_size(#file_info{size=666}). % 14:51:25 <0.205.0>({erlang,apply,2}) % erlang:tuple_size/1 % 14:51:25 <0.205.0>({erlang,apply,2}) % erlang:tuple_size/1 -> 14 redbug done, timeout - 1
Generated by EDoc