View Source edbg (edbg v0.9.0)

edbg - Erlang/Elixir trace and debug tool

edbg is a tty based interface to the Erlang debugger/tracer and the supervisor trees.

This module is the main interface to edbg.

Note that most of the functions here relates to the debugger functionality.

For tracing you only need the functions: fstart/2 , fstop/0, file/0, xfile/0 (and possibly some variants of the argument number).

For the Supervisor Tree Browser, you only need: suptrees/0.

Link to this section Summary

Functions

a()

Attach to the first process found stopped on a break point.

Attach to the given Pid.
Attach to the given process: <P0.P1.P2> .
Attach to the given Pid.
Attach to the given process: <P0.P1.P2> .
Set a break point in 'Mod' at line 'Line'.
Delete all break points.
Delete the break point in 'Mod' on line 'Line'.
Disable all break points.
Disable the break point in 'Mod' on line 'Line'.
Disable all break points.
Enable the break point in 'Mod' on line 'Line'.
Display all break points.
Display all break points for module 'Mod'.
Set a break point in 'Mod' at line 'Line'.
Display all break points.
Display all break points for module 'Mod'.
Continue the execution of the given process 'Pid'.
Continue the execution of the given process <P0.P1.P2>.
Continue the execution of the given process 'Pid'.
Continue the execution of the given process <P0.P1.P2>.
Delete the break point in 'Mod' on line 'Line'.
Delete all break points.
Disable the break point in 'Mod' on line 'Line'.
Disable all break points.
Enable the break point in 'Mod' on line 'Line'.
Disable all break points.
Finish execution of a debugged function in process: 'Pid'.
Finish execution of a debugged function in process: <P0.P1.P2>.
Display a short help text.
As 'file/1' but uses the default trace output filename.

Load the trace output from the file 'Fname'.

Finish execution of a debugged function in process: 'Pid'.
Finish execution of a debugged function in process: <P0.P1.P2>.

Start tracing the process: 'Pid'.

Start tracing the process: 'Pid'.

Start tracing making use of a previously stored configuration.

Start tracing making use of a previously stored configuration.

Start tracing to file.

Stop tracing and dump the trace output to file.

Start interpret the module 'Mod'.

Start interpret module 'Mod' and set a break point at line 'Line'.
Show all interpreted modules.

Start interpret module 'Mod' and set a conditional break point.

Load (previously) stored break points.

Load (previously) stored break points.

As 'mlist/1'.
As 'mlist/2'.
As 'mlist/3'.

List the source code, centered around a break point.

List the source code of a 'Module' centered around 'Row'.

List the source code of a Module.

Same as 'next/1'.
Same as 'next/3'.
Do a 'Next' debug operation of a stopped process: 'Pid'.
Do a 'Next' debug operation of a stopped process: >P0.P1.P2<.
Show all interpreted processes.

Show all interpreted processes.

Same as 'step/1'.
Same as 'step/3'.

Save all current break points.

Save all current break points.

Do a 'Step' debug operation of a stopped process: 'Pid'.
Do a 'Step' debug operation of a stopped process: >P0.P1.P2<.
Enter the Supervisor Tree Browser.

See also: edbg_sup_trees.

As 't/3' but will reuse an existing trigger function.
As 'it/3' but assumes 'Mod' already is interpreted.
As 'file/0' but hint that Elixir code is traced.
As 'file/1' but hint that Elixir code is traced.

Link to this section Functions

Attach to the first process found stopped on a break point.

Attach to an interpreted process in order to manually control the further execution, inspect variables, etc. When called, you will enter a sort of mini-shell where you can issue a number of commands.
Attach to the given Pid.
Attach to the given process: <P0.P1.P2> .
Attach to the given Pid.
Attach to the given process: <P0.P1.P2> .
Set a break point in 'Mod' at line 'Line'.
Delete all break points.
Delete the break point in 'Mod' on line 'Line'.
Disable all break points.
Disable the break point in 'Mod' on line 'Line'.
Disable all break points.
Enable the break point in 'Mod' on line 'Line'.
Display all break points.
Display all break points for module 'Mod'.
Set a break point in 'Mod' at line 'Line'.
Display all break points.
Display all break points for module 'Mod'.
Continue the execution of the given process 'Pid'.
Continue the execution of the given process <P0.P1.P2>.
Continue the execution of the given process 'Pid'.
Continue the execution of the given process <P0.P1.P2>.
Delete the break point in 'Mod' on line 'Line'.
Delete all break points.
Link to this function

disable_break(Mod, Line)

View Source
Disable the break point in 'Mod' on line 'Line'.
Disable all break points.
Enable the break point in 'Mod' on line 'Line'.
Disable all break points.
Finish execution of a debugged function in process: 'Pid'.
Finish execution of a debugged function in process: <P0.P1.P2>.
Display a short help text.
As 'file/1' but uses the default trace output filename.

Load the trace output from the file 'Fname'.

When the file is loaded, enter the trace list mode.
Finish execution of a debugged function in process: 'Pid'.
Finish execution of a debugged function in process: <P0.P1.P2>.

Start tracing the process: 'Pid'.

A qick way of start tracing a process.

The Options are set to be:

    [dump_output_eager,
     send_receive,
     {max_msgs, 1000000}]

Start tracing the process: 'Pid'.

Start tracing the process. The Options are the same as for the 'fstart/2' function-

Start tracing making use of a previously stored configuration.

A previous call to 'fstart/2' will store the configuration on disk so that it can be resued when calling this function.

Start tracing making use of a previously stored configuration.

A previous call to 'fstart/2' will store the configuration on disk so that it can be resued when calling this function.
Link to this function

fstart(ModFunList, Options)

View Source

Start tracing to file.

'ModFunList' is a list of module names (atoms) or tuples {ModuleName, FunctionName}. This makes it possible to trace on all functions within a Module, or just a few functions within a Module.

'Opts' is a list of option tuples:

  • {log_file, FileName} : file where to store trace output; default: 'edbg.trace_result'
  • {max_msgs, MaxNumOfMsgs} : max number of trace messages; default = 1000
  • {trace_time, Seconds} : max time to trace; default = 10 seconds
  • {trace_spec, Spec} : see the erlang:trace/3 docs; default = all
  • dump_output_eager : trace output goes to file often
  • dump_output_lazy : trace output goes to file not so often (default)
  • monotonic_ts : show the elapsed monotonic nano seconds
  • send_receive : trace send/receive messages from 'known' pids
  • memory : track the memory usage of the 'known' pids

Tracing in an Erlang node is setup by the 'erlang:trace/3' and 'erlang:trace_pattern/3' BIF's. The generated trace output in a production system can quickly produce a staggering amount of data, which easily can swamp the whole system, so that it becomes unusable.

It is therefore important to restrict what to trace, the amount of generated trace messages and the maximum time we allow tracing to go on. 'edbg' helps you with this but you can still brake your system if you are careless setting the trace parameters.

With the max_msgs and trace_time parameters you can restrict the amount of generated trace messages and running time before stopping the tracing.

The trace_spec is also a way of restricting what to trace on. Default is all, but for later OTP versions (> 18.3): processes is available and would be more specific. For more info about this, see the 'erlang:trace/3' documentation.

With the dump_output_lazy switch set, trace output goes to file not until the tracer is stopped (e.g by calling the 'file/1' function), or that a limiting filter such as max_msg or trace_time is reached. This is the default.

With the dump_output_eager switch set, trace output goes to file often which may be necessary if you run edbg tracing and the system unexpectedly shuts down.

With the monotonic_ts switch set, each trace message will have a monotonic timestamp, in nanoseconds, attached to it. This will be displayed in the call graph as the elapsed time counted from the first received trace message.

With the send_receive switch set, we will also trace messages sent and received by 'known' pids. By 'known' pids we mean processes that we have seen earlier in a traced call. The reason for this is to avoid beig swamped by all the messages that the trace BIF is sending us. Note that we still may get a lots of messages that will cause the resulting trace file to be large and make the handling of it slower. The display of sent and received messages can be toggled on/off from the trace command prompt, see also the trace examples.

With the memory switch set, we will also track the memory usage of the processes that we get trace messages for. The memory size shown is the size in bytes of the process. This includes call stack, heap, and internal structures, as what we get from the process_info(Pid, memory) BIF.

NOTE: we run the process_info/2 BIF when we receive the trace message from the BEAM engine so the memory size we present does not exactly represent the state of the process at the creation of the trace message.

     % Example, trace calls to the foo module, no more than 1000 trace msgs
     edbg:fstart([foo], [{max_msgs, 1000}]).
     % Example, trace all modules in a particular process,
     % dump the traced output to file often,
     % no more than 1000 trace msgs.
     edbg:fstart([], [{trace_spec,Pid}, dump_output_eager, {max_msgs, 1000}]).
Stop tracing and dump the trace output to file.

Start interpret the module 'Mod'.

With only one argument, you don't set an explicit break point, but you will be able to step into the module while debugging.
Start interpret module 'Mod' and set a break point at line 'Line'.
Show all interpreted modules.

Start interpret module 'Mod' and set a conditional break point.

Start interpret module 'Mod' and set a conditional break point in 'Mod' at line 'Line'. The 'Fun/1' as an anonymous function of arity 1 that gets executed each time the break point is passed. When the 'Fun/1' returns 'true' the break point will trigger and the execution will stop, else the execution will continue.

The 'Fun/1' takes an argument which will be a list of current Variable bindings; typically it makes use of the function 'int:get_binding(Var, Bindings)' (where 'Var' is an atom denoting a particular variable) to decide if the break point should trigger or not. See the example further below for how to use it.

Note that only one interactive trigger function can be used at a time.

Load (previously) stored break points.

Identical to 'load_all_breakpoints/0'.

Load (previously) stored break points.

Whenever a break point is set or modified, information is stored on disk in the file 'breakpoints.edbg' . This function will load and set those breakpoints found in this file.
As 'mlist/1'.
As 'mlist/2'.
As 'mlist/3'.

List the source code, centered around a break point.

The 'mlist/1' can also take a Module as an argument to list the source ode starting from Row 1.
List the source code of a 'Module' centered around 'Row'.

List the source code of a Module.

List the source code of a 'Module', either centered around a triggered break point, or around a given 'Line'. The amount of lines being display around the line is controlled by the 'Contexft' value, which per default is set to '5' (i.e display 5 lines above and below the line).

Note that the listing will display the line numbers at the left border of the output where breakpoints are high lighted by a '*' character and the given line as '>'. However, if no line is given, the '>' character will be used to denote where we currently are stopped.

The 'mlist/3' can also take a sequence of integers for supplying a 'Pid' when we should center around a break point.
Same as 'next/1'.
Same as 'next/3'.
Do a 'Next' debug operation of a stopped process: 'Pid'.
Do a 'Next' debug operation of a stopped process: >P0.P1.P2<.
Show all interpreted processes.

Show all interpreted processes.

Show all interpreted processes and what state there are in. In particular this is useful to see if a process has stopped at a break point. The process identifier ('Pid') displayed in the leftmost column can be used with the 'attach/1' function.
Same as 'step/1'.
Same as 'step/3'.

Save all current break points.

Identical to 'save_all_breakpoints/0'.

Save all current break points.

Whenever a break point is set or modified, information is stored on disk in the file 'breakpoints.edbg' .
Do a 'Step' debug operation of a stopped process: 'Pid'.
Do a 'Step' debug operation of a stopped process: >P0.P1.P2<.
Enter the Supervisor Tree Browser.

See also: edbg_sup_trees.

As 't/3' but will reuse an existing trigger function.
As 'it/3' but assumes 'Mod' already is interpreted.
As 'file/0' but hint that Elixir code is traced.
As 'file/1' but hint that Elixir code is traced.