massemanet/redbug

erlang tracing debugger

DESCRIPTION

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.

DOCUMENTATION

Run rebar3 edoc or check the online docs at hexdocs.

EXAMPLES

Basic call trace

  1> redbug:start("erlang:demonitor").

  % 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, but also 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.)

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

redbug's Issues

Migrating to peer for OTP 25

I'm having some problems with OTP 25 compatibility and redbug.

In OTP 25 the ct_slave module used in redbug unit tests is not supported, with peer recommended instead. Transitioning to peer works OK in the redbug_targ tests, but changing to peer causes problems in the redbug_dist_eunit tests:

{argument_error,{{badfun,#Fun<redbug_targ.1.43499224>},
                               [{erlang,apply,2,[]}]}}

I'm no expert in either the peer module or in redbug, so I'm struggling to work out what I'm doing wrong.

Branch is here - https://github.com/basho/redbug/tree/mas-otp25

Is there anything obvious that I'm missing to make this work?

question - what changed with 2.x versions

I ask because Rexbug (elixir wrapper) is still depending on the 1.x versions, and I'm considering whether to offer to help upgrade to redbug 2.x

Redbug conflicting with cover/excoveralls

Hi,
I'm migrating rexbug to redbug 2.x and I already made the changes to get the basics up and running correctly.

The problem I ran into is that while all the tests run correctly, they fail when running the tests with excoveralls - it seems like redbug isn't able to extract the module/function info for Elixir modules that aren't part of the standard library.

Repro here.

With an elixir module Foo.Bar being defined:

defmodule Foo do
  @moduledoc false
  defmodule Bar do
    @moduledoc false
    def abc() do
    end

    def xyz(_a, _b, _c) do
    end
  end
end

running redbug against it fails:

{:argument_error, :no_matching_functions} = :redbug.start('\'Elixir.Foo.Bar\'')

I verified it's not related the module not being compiled in the test environment or being part of test/support/ as opposed to the main lib/

I suspect that it's caused by coveralls messing with the compilation / code loading, but I don't understand what's happening exactly. I checked that the :cover compile path (as it is used inside coveralls) is included in :code.get_path() and it is - making sure it's the first path in the list doesn't change anything.

If anyone has an idea what can be done (whether is a change to my approach, or patching either coveralls or redbug) so that I can keep the code coverage, I'd appreciate it.

Why redbug can not trace the un-exported function? What should I set?

as the following pic. the function handle is exported, and function select_option is not exported

Promote the latest changes to Hex

Hello,

Would it be possible to promote the latest changes (April 2023) to Hex?

Thank you!
Boris

is_map_key not allowed in guards

Repro when called from Elixir:

iex> :redbug.start('maps:size(X) when is_map(X)')       
{110, 1}
iex> :redbug.stop()                                                  
:stopped
redbug done, stopped - 0
iex> :redbug.start('maps:size(X) when is_map_key(a, X)')
{:parse_error, 'syntax error before: \'(\''}

The guard is available since OTP 21, I know you already do some special casing for OTP versions.

It definitely isn't a big deal, but it stops me from developing the is_struct() guard in rexbug 2.x

I'm going to drop the is_struct() as a feature for now, but if there are any changes on this front I'd be very interested.

Thanks!

assert_dir/1 is broken for [] as input

When running the Erlang VM with $CWD in read-only, redbug:assert_dir/1 returns read as the file_info. When the output file is [] it defaults to standard_io in redbug:get_fd/1 and in those cases assert_dir/1 should be a no-op.

target (node()) node to trace on -> target (node()|[node()]) node(s) to trace on

First off, thanks for making such an awesome library, I have so much fun using Redbug, thanks for that.

A question - is it feasable to modify the behavior of rebug so it traces on multiple nodes?

My issue is that I tend to run traces on Riak nodes, for learning, demos, and debugging live issues, but the events can execute on any of N+ machines, where N is normally more than 5 (recommended size of a Riak cluster.

I could drop down to traditional tracing, but it scares people (including me) as it doesn't with any of the Redbug safety mechanisms - as a consequence, I tend to just randomly pick nodes and hope they will see the events.

There is quite possibly a reason why this functionality wasn't implemented, so this issue is also asking if that is by design.

Redbug over rpc IO error

As reported here http://erlang.org/pipermail/erlang-questions/2018-November/096669.html

Start two nodes

erl -name  -setcookie trc -pa PATH_TO_EPER_BIN
erl -name  -setcookie trc

in the second node () I run the following:

3> net_kernel:hidden_connect('').
 true
 ()4> rpc:call('', redbug, start,
["erlang:term_to_binary", [{arity, true}, {print_file,
"/home/russell/t2btrc"}]]).
 {40,2}
 ()5> rpc:call('', erlang, term_to_binary,
[{my_tuple, is, boss}]).
 <<131,104,3,100,0,8,109,121,95,116,117,112,108,101,100,0,
   2,105,115,100,0,4,98,111,115,115>>
 ()6>
=ERROR REPORT==== 13-Nov-2018::16:48:17 ===
Error in process <0.46.0> on node '' with exit value:
{terminated,[{io,format,[<0.44.0>,"~s~n",["\n16:48:17 <0.52.0>(dead)
{erlang,term_to_binary,1}"]],[]},{redbug,'-mk_outer/1-fun-2-',5,[{file,"src/redbug.erl"},{line,343}]},{redbug,'-wrap_print_fun/1-fun-0-',3,[{file,"src/redbug.erl"},{line...

redbug done, terminated - [{io,format,
                             [<5930.44.0>,"~s~n",
                              ["\n16:48:17 <0.52.0>(dead)
{erlang,term_to_binary,1}"]],
                             []},
                         {redbug,'-mk_outer/1-fun-2-',5,
                                 [{file,"src/redbug.erl"},{line,343}]},
                         {redbug,'-wrap_print_fun/1-fun-0-',3,
                                 [{file,"src/redbug.erl"},{line,329}]},
                         {lists,foldl,3,[{file,"lists.erl"},{line,1248}]},
                         {redbug,print_loop,2,
                                 [{file,"src/redbug.erl"},{line,519}]}]

AND the file "/home/russell/t2btrc" is empty, but created.

However, if I run

         ()1> redbug:start("erlang:term_to_binary", [{arity,
true}, {print_file, "/home/russell/t2btrc"}]).
         {38,2}
         ()2> erlang:term_to_binary({my_tuple, is, boss}).
         <<131,104,3,100,0,8,109,121,95,116,117,112,108,101,100,0,
           2,105,115,100,0,4,98,111,115,115>>
           redbug done, timeout - 1
           ()3>

In the node () the file is created and contains

   16:49:39 <0.39.0>({erlang,apply,2}) {erlang,term_to_binary,1}

I expected running the rpc calls to result in the same outcome as running locally. Is this a bug in my thinking, redbug, or something else?

Both nodes are on the same physical host and have access to the file path.

[question] Matching on maps not supported?

When playing around with redbug (which I loved right out of the gate) I realized it doesn't support matching maps in the trace pattern arguments:

10> redbug:start("erlang:term_to_binary([])").
{38,1}
redbug done, timeout - 0
11> [A, B, C] = "#\{\}".
"#{}"
12> redbug:start("erlang:term_to_binary(#\{\})").
{bad_type,{map,[]}}
13> redbug:start("erlang:term_to_binary(X) when X == 1").
{38,1}
14> redbug:stop().
stopped
redbug done, local_done - 0
15> redbug:start("erlang:term_to_binary(X) when #\{\} = X").
{function_clause,{parse_guards,"erlang:term_to_binary(X) when #{} = X"},
                 [{redbug_msc,arg,
                              [{match,1,{map,1,[]},{var,1,'X'}}],
                              (... more errors cut)

After looking at the source code, I think it's intentional.

While I'm not questioning the decision, I'm curious to the motivation. Is there any reason in particular why matching maps isn't supported in the trace pattern?

Thanks in advance and sorry to bother you with this GitHub issue.

question, is it possible to specify an Elixir module name

Hi, from (quickly, stupidly) reading the code for the lexer.

https://github.com/massemanet/redbug/blob/master/src/redbug_lexer.xrl#L86-L90

[a-z][A-Z0-9a-z_]* :
  {token, {'atom', TokenLine, to_atom(TokenChars)}}.

'([^'|\\'])*' :
  {token, {'atom', TokenLine, to_atom(trim(TokenChars))}}.

Seems like it can parse atoms with Upper case, such as 'FG' but not atoms with periods, such as 'My.Favorite.Atom'.

Is this right? I'm trying to use redbug to trace Elixir module invocations. Specifically, invocations with specific Map k => v as the first arg.

Default branch still points to master

2.0.9 is the latest version but only according to the main branch. Also I couldn't find a tag for 2.0.9.

Matching binaries

Hi! I wonder if it would make sense/ be desirable to add support for matching binaries to the Redbug syntax. In addition to the following (already supported) syntax:

redbug:start("x:y(<<\"hello\">>)").

One could also write:

redbug:start("x:y(<<\"he\",_/binary>>)").

Or even something like:

redbug:start("wow:do(<<_:8,_:8,0,_/binary>>").