DOCSEARCHbyAlgolia
Submit Docs

redbug

repository·master·Indexed 42 days ago

https://github.com/massemanet/redbug

A tool for interacting with the Erlang trace facility to monitor function calls, return values, and message passing. It can be used within an Erlang shell via the redbug:start/2 API or as a standalone escript from the OS shell for tracing remote nodes.

Tokens
996
Snippets
3
Records
4
Agent score
3%

What's inside redbug

  1. How redbug tracing works

    master

    redbug uses a safe subset of the Erlang tracing functionality to collect 'trace messages' when specific events occur.

    Key Concepts:

    • Termination Criteria: Tracing runs in the background until it hits a limit: number of messages (msgs), file size, or elapsed time (timeout).
    • Output Modes:
      • Printed: Human-readable messages sent to the screen/shell (default).
      • File (.trc): Written to a .trc file. This is lower stress on the system but requires special tools like bread to read. You cannot combine printed output and .trc files.
    • Safety: The tool is designed to exit if it becomes overloaded (e.g., flooded by messages) to prevent crashing the target system.

  2. Use redbug in the Erlang shell

    master

    You can interact with the Erlang trace facility directly from an Erlang shell using the redbug:start/2 function. This allows you to instruct the VM to generate trace messages for specific events like function calls.

    By default, messages are printed to the screen. You can also specify termination criteria such as a maximum number of messages (msgs), file size, or elapsed time. If you provide a file option, messages are written to a .trc file instead of being printed (note: msgs is ignored when using .trc files).

    %% Basic call trace
redbug:start("erlang:demonitor").

%% Trace with return value and limit to 2 messages
redbug:start("erlang:demonitor->return", [{msgs, 2}]).

%% Trace with call stack and limit to 2 messages
redbug:start("erlang:demonitor->return,stack", [{msgs, 2}]).

%% Blocking mode: waits until trace ends and returns {Reason, Messages}
redbug:start("ets:tab2list(inet_db)", [blocking]).

  3. Use redbug as an escript from the OS shell

    master

    redbug can be run as a standalone portable escript from your operating system's command line. This is useful for tracing remote nodes.

    Syntax: ./redbug [-Opt Value [...]] TargetNode Trc [Trc...]

    • TargetNode: The name of the Erlang node to trace.
    • Trc: The trace pattern (e.g., a function call or a receive event).
    • -Opt Value: Options like -msgs to limit the number of messages.
    %% Trace a node named 'foo' for a specific function
$ redbug foo erlang:demonitor

%% Limit message count to 1
$ redbug foo erlang:demonitor -msgs 1

%% Trace return values and limit to 2 messages
$ redbug foo 'erlang:demonitor -> return' -msgs 2

%% Trace messages received by a specific process
$ redbug foo receive -procs user_drv -msgs 1

  4. redbug:start/2 API reference

    master

    Starts a tracing session within the Erlang shell.

    Arguments:

    • Pattern (String): The trace pattern to match (e.g., "erlang:demonitor", "erlang:demonitor->return,stack").
    • Options (List, optional): A list of configuration options.

    Common Options:

    • {msgs, N}: Terminate after N messages are collected.
    • blocking: The function call will block until the trace reaches a termination criterion, returning {Reason, Messages}.

    Return Values:

    • In non-blocking mode: Returns nothing (traces are printed to the shell).
    • In blocking mode: Returns {StopReason, TraceMessages} (e.g., {timeout, [...]} or {msg_count, [...]}).
    %% Example of blocking call
redbug:start("ets:tab2list(inet_db)", [blocking]).