Dbg v1.0.1 → Overview → Dbg

Dbg

Summary
Functions

Dbg provides functions for tracing events in the BEAM VM.

Many events, including function calls and return, exception raising, sending and receiving messages, spawning, exiting, linking, scheduling and garbage collection can be traced across a cluster of nodes using Dbg.

Configuration

To configure the output device for Dbg the Application env variable :device to an IO.device or {:file, Path.t}. In the later case a binary format is used to write to the file that can be read later using Dbg.inspect_file/2. The default is to send output to the :user process.

When outputting to an IO.device, or when reading a binary trace file, the colours and inspection of terms use IEx's configuration. Dbg uses two extra colour settings not supported by IEx:

trace_info - the colour used to print trace messages
trace_app - the colour to print application names in stacktraces

These are configured like the other IEx colour settings. The default is to print in magenta, with application names bright,magenta in stacktraces.

Source

Summary↑

call(target, pattern \\ nil)	Set call tracing for global function calls
cancel(target)	Cancels all tracing for a `target` set by `Dbg.call/2` or `Dbg.local_call/2`
clear(item \\ self())	Turns off all tracing flags for an `item`
clear_node(node_name)	Turns off tracing processes on a foreign node by the local `Dbg` process
flush()	Blocks while trace events are delivered and (when outputting to file) any data is flushed to disk
inspect_file(device \\ :standard_io, file)	Prints (and formats) a binary trace file to the `IO.device`
local_call(target, pattern \\ nil)	Set call tracing for local (and global) function calls
node(node_name)	Turns on tracing for processes on a foreign node by the local `Dbg` process
nodes()	Lists all nodes being traced by the local `Dbg` process
patterns()	Returns all stored `pattern`'s for use with `Dbg.call/2` and `Dbg.local_call/2`
reset()	Reset `Dbg` to remove all tracing and create a new tracing process
trace(item \\ self(), flags)	Turns on tracing `flags` for `item`

Functions

call(target, pattern \\ nil)

(function) # ↑

Specs:

call(fun_call, pattern) :: %{}

Set call tracing for global function calls.

target takes one of the following forms:

module - traces all functions in the module
{module, atom} - trace all function's with the name in the module
{module, atom, arity} - trace the function name with arity in the module
fun - trace calls equivalent to fun (must be an external fun, e.g. &module.fun/arity)

pattern takes one of the following forms:

:c - call traces will include the calling function where possible
:x - adds tracing of the return value or raising of the call
:xc - equivalent to :c and :x
integer - the saved id of a previous pattern
[option] or option - can be an empty list, see below
match_spec - see below

option takes one of the following forms:

:caller - call traces will include the calling function where possible
:exception - adds tracing of the return value or raising of the call
:return - adds tracing of the return value of the call
:stack - adds a full stacktrace to the call trace events
{:trace, [flag] | flag} - adds the trace flags to the calling process when a function matching the pattern is called, equivalent to calling Dbg.trace([flag]) in the calling process
{:trace, pid, [flag] | flag} - adds the trace flags to pid when a function matching the pattern is called, equivalent to calling Dbg.trace(pid, [flag])
:clear - clears all trace flags from the calling process when a function matching the pattern is called, equivalent to calling Dbg.clear() in the calling process
{:clear, pid} - clears all trace flags from the pid when a function matching the pattern is called, equivalent to calling Dbg.clear(pid)
{:silent, boolean} - turns on or off the :silent trace flag in the calling process when a function matching the pattern is called.

match_spec must be a match spec that matches on a list (or a variable) and returns a list of option's, or an empty list. Some complex match specs may not be allowed.

A global function call is a call to an external module, i.e. a call that includes the module name. Mod.function() is a global call but function() is a local call. To trace both global and local calls use Dbg.local_call/2.

For example:

# Trace calls to all functions in Map
Dbg.call(Map)

# Trace calls to Map.new()
Dbg.call({Map, new, 0})

# Or equivalently:
Dbg.call(&Map.new/0)

# Include the stacktrace in trace events for the call  Map.new()
Dbg.call(&Map.new/0, [:stack])

# Trace the call and return of Enum.map/2 calls
Dbg.call(&Enum.map/2, [:return])

# Hide the call trace events of the calling process when GenServer.call/2
# is called and reuse the pattern for GenServer.call/3
%{saved: saved} = Dbg.call(&GenServer.call/2, [silent: true])
Dbg.call(&GenServer.call/3, saved)

# Turn on the :send flag in the process pid when Map.new() is called
Dbg.call(&Map.new/0, {:trace, pid, [:send]}

# Clear tracing flags in the calling process when Enum.map/2 is called
# with a list as the first argument:
Dbg.call(&Enum.map/2, [{[:"$1", :_], [{:is_list, :"$1"}], [:clear]}])

Source

cancel(target)

(function) # ↑

Specs:

cancel(fun_call) :: %{}

Cancels all tracing for a target set by Dbg.call/2 or Dbg.local_call/2.

For example:

# Cancel the tracing of all functions in Map
Dbg.cancel(Map)

# Cancel the tracing of Map.new() calls
Dbg.cancel(&Map.new/0)

Source

clear(item \\ self())

(function) # ↑

Specs:

clear(item) :: %{}

Turns off all tracing flags for an item.

For a list of items see trace/2.

For example:

# Clear tracing flags from self()
Dbg.clear()

# Clear tracing flags from all processes
Dbg.clear(:all)

Source

clear_node(node_name)

(function) # ↑

Specs:

clear_node(node) :: :ok

Turns off tracing processes on a foreign node by the local Dbg process.

For example:

# Stop tracing :node@host
Dbg.clear_node(:node@host)

Source

flush()

(function) # ↑

Specs:

flush :: :ok

Blocks while trace events are delivered and (when outputting to file) any data is flushed to disk.

If the outputting to a IO.device does not guarantee that the trace events have been sent, only that they have been received by the tracer.

Source

inspect_file(device \\ :standard_io, file)

(function) # ↑

Specs:

inspect_file(IO.device, Path.t) :: :ok | {:error, any}

Prints (and formats) a binary trace file to the IO.device.

For example:

# Print trace events from "dbg.log" to :standard_io
Dbg.inspect_file("dbg.log")

Source

local_call(target, pattern \\ nil)

(function) # ↑

Specs:

local_call(fun_call, pattern) :: %{}

Set call tracing for local (and global) function calls.

The the same as Dbg.call/2 except will trace all function calls.

Source

node(node_name)

(function) # ↑

Specs:

node(node) :: :ok

Turns on tracing for processes on a foreign node by the local Dbg process.

Can not add nodes whe tracing to file, consider using Dbg on the foreign node as well.

For example:

# Start tracing :node@host
Dbg.node(:node@host)

Source

nodes()

(function) # ↑

Specs:

nodes :: [node]

Lists all nodes being traced by the local Dbg process.

Source

patterns()

(function) # ↑

Specs:

patterns :: %{}

Returns all stored pattern's for use with Dbg.call/2 and Dbg.local_call/2.

Source

reset()

(function) # ↑

Specs:

reset :: :ok

Reset Dbg to remove all tracing and create a new tracing process.

Source

trace(item \\ self(), flags)

(function) # ↑

Specs:

trace(item, flag | [flag]) :: %{}

Turns on tracing flags for item.

item takes one of the following forms:

:all - all current and future processes
:new - all future processes
:existing -all current processes
pid - a process
atom - a locally registered process
{atom, node} - a locally registered process on another node
{:global, term} - a globally registered process
{:via, module, term} - a process registered using a :via module

flags is a list or a single flag:

:send (or :s) - will trace all messages sent by the item
:receive (or :r) - will trace all messages received by the item
:messages (or :m) - is the equivalent of :send and :receive
:call (or :c) - will turn on call tracing (see call/2) for the item
:arity - used in combination with :call will not include function arguments in the item's call trace events
:return_to - used in combination with :call will show which function (and when) a call returns to
:silent - used in combination with :call will hide all the item's call trace events
:procs (or :p) - will trace all process events by the item
:running - will trace when the item is scheduled in and out
:garbage_collection - will trace garbage collection events by the item
:set_on_spawn (or :sos) - will cause processes spawned by the item to in herit the item's trace flags
:set_on_first_spawn (or :sofs) - will cause the first process spawned by the item to in herit the item's trace flags.
:set_on_link (or :sol) - will cause a process linked to by the item to inherit the item's trace flags
:set_on_first_link (or :sofl) - will cause the first process linked to by the item to inherit the item's trace flags
:timestamp - will add a timestamp to all of the item's traced events

For example:

# Trace all messages of self(), and any messages for processes it spawns
Dbg.trace([:messages, :set_on_spawn])

# Turn on call tracing for process registered as :name but don't include
# function arguments
Dbg.trace(:name, [:call, :arity])

# Trace the scheduling of :name on node :node@host including the time
Dbg.trace({:name, :node@host}, [:running, :timestamp])

Source