View Source edbg (edbg v0.9.2)
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).
suptrees/0
.
Link to this section Summary
Functions
Attach to the first process found stopped on a break point.
Load the trace output from the file 'Fname'.
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.
Start interpret the module 'Mod'.
Start interpret module 'Mod' and set a conditional break point.
Load (previously) stored break points.
Load (previously) stored break points.
List the source code, centered around a break point.
List the source code of a Module.
Show all interpreted processes.
Save all current break points.
Save all current break points.
See also: edbg_sup_trees.
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.Load the trace output from the file 'Fname'.
When the file is loaded, enter the trace list mode.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.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'
- {cfg_file, FileName} : file where to store the config; default: 'ftrace.edbg'
- {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}]).
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 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.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.
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.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.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' .See also: edbg_sup_trees.