View Source edb (edb v0.3.0)
The (new!) Erlang debugger
Summary
Functions
Set a breakpoint on the line of a loaded module on the remote node.
Start a debugging session by attaching to the given node.
Returns the node being debugged.
Clear a previously set breakpoint on the remote node.
Clear all previously set breakpoints of a module on the remote node.
Continues the execution on the remote node and returns right away.
Detach from the currently attached node.
Add a single process to the set of processes excluded from debugging. It is equivalent to exclude_processes([{proc, Proc}])
.
Extend the set of processes excluded by the debugger.
List the pids that will not be stopped by the debugger on the remote node.
Get all currently set breakpoints on the remote node.
Get the list of processes currently stopped at a breakpoint on the remote node.
Check if there exists paused processes.
Get information about a process managed by the debugger on the remote node.
Get the set of processes managed by the debugger on the remote node.
Request that a sync
event is sent to the given subscription.
Get the local variables for a paused processes at a give frame.
Get the local variables for a paused process at a given frame.
Get the stack frames for a paused process.
Subscribe caller process to receive debugging events from the attached node.
Terminates the debugging session.
Removes an exclusion previously added with exclude_processes/1
.
Remove a previously added subscription.
Waits until any process gets stopped.
Types
-type arg_parser(A) :: fun((term()) -> A).
-type catch_handler() :: {'catch', {mfa(), {line, pos_integer() | undefined}}}.
-type event() :: {resumed, resumed_event()} | {stopped, stopped_event()} | {sync, reference()} | {terminated, Reason :: term()} | unsubscribed | {nodedown, node(), Reason :: term()}.
-type event_envelope(Event) :: {edb_event, event_subscription(), Event}.
-type event_subscription() :: edb_events:subscription().
-type excluded_process_info() :: #{application => atom(), current_fun => mfa(), current_loc => {string(), line()}, parent => atom() | pid(), reason => [exclusion_reason()], registered_name => atom(), message_queue_len => non_neg_integer()}.
-type exclusion_reason() ::
debugger_component | excluded_application | excluded_pid | excluded_regname | system_component.
-type frame_id() :: non_neg_integer().
-type fun_name() :: atom().
-type line() :: pos_integer().
-type process_info() :: #{status := process_status(), application => atom(), current_fun => mfa(), current_loc => {string(), line()}, current_bp => {line, line()}, parent => atom() | pid(), registered_name => atom(), message_queue_len => non_neg_integer()}.
-type process_status() :: running | paused | breakpoint.
-type resumed_event() :: {continue, all} | {excluded, #{pid() => []}} | {termination, all}.
-type stack_frame() :: #{id := frame_id(), mfa := mfa() | unknown, source := file:filename() | undefined, line := line() | undefined}.
-type start_error() :: unsupported | failed_to_register.
-type step_error() :: no_abstract_code | not_paused | {beam_analysis, term()}.
-type step_out_error() :: step_error().
-type step_over_error() :: step_error().
-type stopped_event() :: {breakpoint, pid(), mfa(), {line, pos_integer()}} | {step, pid()} | {paused, all | #{pid() => []}}.
-type value() :: {value, term()} | {too_large, Size :: pos_integer(), Max :: pos_integer()}.
Functions
-spec add_breakpoint(Module, Line) -> ok | {error, Reason} when Module :: module(), Line :: pos_integer(), Reason :: edb:add_breakpoint_error().
Set a breakpoint on the line of a loaded module on the remote node.
-spec attach(#{node := node(), timeout => timeout()}) -> ok | {error, Reason} when Reason :: attachment_in_progress | nodedown | start_error() | term().
Start a debugging session by attaching to the given node.
If edb was already attached to a node, it will get detached first. The attached node may already have a debugging session in progress, in this case, edb joins it.
Arguments:
* node
- the node to attach to * timeout
- how long to wait for the node to be up; defaults to 0
-spec attached_node() -> node().
Returns the node being debugged.
Will raise a not_attached
error if not attached.
-spec clear_breakpoint(Module, Line) -> ok | {error, Reason} when Module :: module(), Line :: pos_integer(), Reason :: {unsupported, Module | Line} | {badkey, Module | Line}.
Clear a previously set breakpoint on the remote node.
-spec clear_breakpoints(Module) -> ok when Module :: module().
Clear all previously set breakpoints of a module on the remote node.
-spec continue() -> {ok, resumed | not_stopped}.
Continues the execution on the remote node and returns right away.
Returns not_stopped
if no process was paused, otherwise resumed
.
-spec detach() -> ok.
Detach from the currently attached node.
The debugger session running on the node is left undisturbed.
Add a single process to the set of processes excluded from debugging. It is equivalent to exclude_processes([{proc, Proc}])
.
-spec exclude_processes(Specs) -> ok when Specs :: [procs_spec()].
Extend the set of processes excluded by the debugger.
Processes can be specified in the following ways: - by pid, - by being part of an application, - exception list for pids that should not be excluded
E.g. a spec like:
[Pid1, {appication, foo}, {application, bar}, {except, Pid2}, {except, Pid3}]
will exclude Pid1
and all processes in applications foo
and bar
; however Pid2
and Pid3
are guaranteed not to be excluded, whether they are part of foo
, bar
, etc. The order of the spec clauses is irrelevant and, in particular, except
clauses are global.
If any specified processes are currently paused, they will be automatically resumed.
-spec excluded_processes() -> #{pid() => []}.
List the pids that will not be stopped by the debugger on the remote node.
-spec get_breakpoints() -> #{module() => [breakpoint_info()]}.
Get all currently set breakpoints on the remote node.
-spec get_breakpoints_hit() -> #{pid() => breakpoint_info()}.
Get the list of processes currently stopped at a breakpoint on the remote node.
-spec is_paused() -> boolean().
Check if there exists paused processes.
-spec process_info(pid()) -> {ok, process_info()} | undefined.
Get information about a process managed by the debugger on the remote node.
-spec processes() -> #{pid() => process_info()}.
Get the set of processes managed by the debugger on the remote node.
-spec send_sync_event(Subscription) -> {ok, SyncRef} | undefined when Subscription :: event_subscription(), SyncRef :: reference().
Request that a sync
event is sent to the given subscription.
The process holding the subscription will receive a sync
event, with the returned reference as value. This can be used to ensure that there are no events the server is planning to send.
Returns {error, unknown_subscription}
if the subscription is not known.
-spec stack_frame_vars(Pid, FrameId) -> not_paused | undefined | {ok, Result} when Pid :: pid(), FrameId :: frame_id(), Result :: stack_frame_vars().
Get the local variables for a paused processes at a give frame.
Equivalent to stack_frame_vars(Pid, 2048)
.
-spec stack_frame_vars(Pid, FrameId, MaxTermSize) -> not_paused | undefined | {ok, Result} when Pid :: pid(), FrameId :: frame_id(), MaxTermSize :: pos_integer(), Result :: stack_frame_vars().
Get the local variables for a paused process at a given frame.
The value of FrameId` must be one of the frame-ids returned by `stack_frames/1
, or the call will return undefined
.
For each variable, the value is returned only if its internal size is at most MaxTermSize
, otherwise {too_large, Size, MaxTermSize}
is returned. This is to prevent the caller from getting objects that are larger than they are willing to handle.
-spec stack_frames(Pid) -> not_paused | {ok, [Frame]} when Pid :: pid(), Frame :: stack_frame().
Get the stack frames for a paused process.
The FrameNo
can then be used to retrieve the variables for a particular frame.
-spec step_out(pid()) -> ok | {error, step_out_error()}.
-spec step_over(pid()) -> ok | {error, step_over_error()}.
-spec subscribe() -> {ok, event_subscription()}.
Subscribe caller process to receive debugging events from the attached node.
The caller process can then expect messages of type event_envelope(event())
, with the specified subscription in the envelope. A process can hold multiple subscriptions and can unsubscribe from them individually.
-spec terminate() -> ok.
Terminates the debugging session.
Detaches from the node, but stopping the debugger running on it. That means that breakpoints will be cleared, and any paused processes will be resumed, etc.
-spec unexclude_processes(Specs) -> ok when Specs :: [procs_spec()].
Removes an exclusion previously added with exclude_processes/1
.
If there are currently paused processes, any specified processes will be paused as well.
-spec unsubscribe(Subscription) -> ok when Subscription :: event_subscription().
Remove a previously added subscription.
The caller process need not be the one holding the subscription. An unsubscribed
event will be sent as final event to the subscription, which marks the end of the event stream.
-spec wait() -> {ok, stopped}.
Waits until any process gets stopped.