Prints the help message / usage manual to standard output.

The help message is as follows:

Rexbug - a thin Elixir wrapper for :redbug - the (sensibly) Restrictive
Debugger. It doesn't fork :redbug, only uses it under the hood.

You can use :redbug directly - run :redbug.help() to see its help message.

Inner workings:
  Rexbug 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.
  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.


Basic usage:
  Rexbug.start(trace_pattern, opts \ [])
  Rexbug.start(time_limit, message_limit, trace_pattern)

trace_pattern:  :send | :receive | rtp | [:send | :receive | rtp]

rtp:  restricted trace pattern
  the rtp has the form: "<mfa> when <guards> :: <actions>"
  where <mfa> can be:
    "Mod", "Mod.fun/3", "Mod.fun/_" or "Mod.fun(_, :atom, x)"

  <guard> is something like:
    "x==1" or "is_atom(a)"

  and <actions> is:
    "", "return", "stack", or "return;stack"

  E.g.
    :ets.lookup(t, :hostname) when is_integer(t) :: stack
    Map.new/2
    Map.pop(_, :some_key, default) when default != nil :: return
    Agent

NOTE: The <mfa> of "Map.new" is equivalent to "Map.new()" - the 0 arity
is implied. To trace the function with any arity use "Map.new/any" or
simply "Map.new/_".

opts: Keyword.t
  general opts (and their default values):

time         (15_000)      stop trace after this many ms
msgs         (10)          stop trace after this many msgs
target       (Node.self()) node to trace on
cookie       (host cookie) target node cookie
blocking     (false)       block start/2, return a list of messages
arity        (false)       print arity instead of arg list
buffered     (false)       buffer messages till end of trace
discard      (false)       discard messages (when counting)
max_queue    (5_000)       fail if internal queue gets this long
max_msg_size (50_000)      fail if seeing a msg this big
procs        (:all)        (list of) Erlang process(es)
                            :all|:new|pid()|atom(reg_name)|{:pid,i2,i3}
  print-related opts:
print_calls  (true)        print calls
print_file   (standard_io) print to this file
print_msec   (false)       print milliseconds on timestamps
print_depth  (999_999)     formatting depth for "~P"
print_re     ("")          print only messages that match this regex
print_return (true)        print return value (if "return" action given)
print_fun    ()            custom print handler, fun/1 or fun/2;
                            fun(trace_msg :: term) :: <ignored>
                            fun(trace_msg, acc_old) :: acc_new
                           (where initial accumulator is 0)
  trc file related opts:
file         (none)        use a trc file based on this name
file_size    (1)           size of each trc file
file_count   (8)           number of trc files

See Rexbug.start/2.

Starts tracing for the given pattern with provided options.

If successful and :blocking option is not specified, returns a tuple where the first element is the count of targeted processes and the second element is the count of targeted functions

Trace Pattern

The trace_pattern is a string (binary) describing which function(s) should be traced.

The trace_pattern has the "<mfa> when <guards> :: <actions>" form, where guards and actions are optional and <mfa> can be in the form of Mod, Mod.fun/3, Mod.fun/_ or Mod.fun(_, :atom, x)

Most normal Elixir guards are valid as <guards>, so something like x==1 or is_atom(x) or is_integer(i) and i > 0 would work.

The valid <actions> are: return, stack, or return;stack

Apart from tracing function calls you can trace sent and received messages. To do so specify :send or :receive as the trace pattern.

You can also specify multiple trace patterns by providing a list of them as the first argument.

Options

There's a range of options that modify the behaviour of Rexbug.

General options

Print-related options

Trace file related options

Options comments

:blocking

If set to true, instead of printing traces to stdio, Rexbug.start/2 will block and return a list of trace messages when it's done tracing.

:procs

Which processes to trace. The possible values are :all for all processes, :new for just the ones spawned after the tracing has started, an atom for registered processes, or a pid. The pid can either be a PID literal or a {:pid, x, y}, where x and y are the latter 2 integers from the PID representation. So for example #PID<0.150.0> could be expressed with {:pid, 150, 0}.

The first integer from the PID representation is omitted, because it represents the node number. You can use the target option to specify a remote node instead.

You can provide either a single process or a list of procs to trace.

:print_fun

Custom function to use to print the trace messages.

The function can be in the fun(trace_msg :: term) :: <ignored> format or the fun(trace_msg, acc_old) :: acc_new format. If you use the latter format, the initial accumulator will be 0.

See Rexbug.start/2.

See Rexbug.start/2.

See Rexbug.start/2.

Stops all tracing.

Stops all tracing in a synchronous manner.

Usually there's no need to use this function over stop/0. You might want to use it if you're going to start tracing immediately afterwards in an automated fashion.