Отладка средствами trace/dbg/sys

http://www.erlang.org/doc/man/erlang.html#trace-3

У функции 3 аргумента.

PidSpec указывает, какие процессы мы хотим трассировать. How это флаг, включающий или выключающий трассировку. FlagList указывает, какие события на этих процессах мы хотим трассировать.

PidSpec имеет варианты:

• Pid процесса
• атомы: existing, new, all;

existing – трассировать имеющиеся процессы, игнорировать новые, которые создаются уже после того, как трассировка включена. new – наоборот, игнорировать имеющиеся процессы, трассировать новые. all – трассировать все процессы.

FlagList имеет много вариантов. Рассмотрим некоторые.

• send, 'receive' – трассировать отправку/получение сообщений
• procs – трассировать события жизненного цикла процесса и связи между процессами: spawn, exit, link, unlink, getting_linked, getting_unlinked, register, unregister
• call – трассировать вызовы функций (подробности ниже)
• running – трассировать работу планировщика процессов
• garbage_collection – трассировать сборку мусора

Когда включена трассировка, генерируются специальные сообщения вида:
{trace, Pid, EventTag, Data1 [,Data2]}

Например:
{trace, Pid, 'receive', Msg} - процесс Pid получил сообщение Msg
{trace, Pid, send, Msg, To} - процесс Pid отправил сообщение Msg процессу To
{trace, Pid, call, {M, F, Args}} - процесс Pid начал выполнение функции {M, F, Args}
и т.д.

Кто получает эти сообщения? По умолчанию тот процесс, который вызвал erlang:trace. Но можно при вызове указать в FlagList аргумент {tracer, Pid}, и сделать получателем сообщений какой-нибудь другой процесс.

Процесс-получатель называется tracer process, и он может быть только один. По понятным причинам, для него самого трассировку включить нельзя.

http://www.erlang.org/doc/man/erlang.html#trace_pattern-3

Итак, мы теперь можем выбрать, какие процессы хотим трассировать. Но обычно нам интересно наблюдать вызовы функций, аргументы и возвращаемые значения.

Для этого нужно вызвать еще и erlang:trace_pattern/3.

И мы будем получать события трассировки, когда заданные в erlang:trace процессы будут вызывать заданные в erlang:trace_pattern функции.

Тут аргументы посложнее :)

Первый аргумент MFA указывает функцию, которую мы хотим трассировать. Это кортеж {Module, Function, Arity}, который однозначно указывает функцию. Но он допускает wildcards, и так может указывать на несколько функций:

• {Module, Function, '_'} – все функции с таким именем и любым Arity;
• {Module, '_', '_'} – все функции данного модуля;
• {'_', '_', '_'} – вообще все функции.

Второй аргумент, MatchSpec, сложнее.

Во-первых, он используется для включения-выключения трассировки (как и в erlang:trace) если задать значения true/false.

Во-вторых, может управлять счетчиками вызовов функций, и счетчиками времени выполнения функций. Подробности в документации.

И, наконец, можно задать собственно match specification, чтобы событие трассировки генерировалось не для любого вызова функции, а в зависимости от аргументов. Подробности ниже.

Третий аргумент, TraceFlags, добавляет еще некоторые опции:

• global – трассировать только глобальные вызовы;
• local – трассировать любые вызовы (и глобальные и локальные)
• call_count – включает счетчик вызовов функции;
• call_time – добавляет время выполнения функции в событие трассировки.

Глобальный вызов, это вызов экспортированной функции с указанием модуля:
my_module:my_func(Arg).

А вот это локальный вызов:
my_func(Arg).

PidSpec имеет варианты:

• Pid процесса в разных формах (собственно Pid, кортеж {N, N, N}, строка "<N.N.N>");
• имя, под которым процесс зарегистрирован;
• атомы: existing, new, all;

FlagLists принимает аналогичные значения, как в erlang:trace, но в лаконичном виде:

• s (send), r (received), m (message = send + receive)
• p (procs) события spawn, exit, link, unlink, getting_linked, getting_unlinked, register, unregister
• c (call)

Таким образом вызов:

dbg:p({0.55.0}, m)

аналогичен вызову:

erlang:trace({0.55.0}, [true], [send, 'receive'])

Оберкта для erlang:trace_pattern, выполняет:

erlang:trace_pattern({Mod, Fun, Args}, true, FlagList),
apply(Mod, Fun, Args),

То есть, задает trace_pattern для функции, и тут же ее вызывает. Удобный способ, чтобы быстро отладить конкретную функцию.

Причем вызов dbg:c должен идти в паре с вызовом dbg:p, так же, как в паре идут erlang:trace и erlang:trace_pattern

Есть вариант dbg:c(Mod, Fun, Args), без указания FlagList. В этом случае автоматически устанавливаются все флаги.

Тоже обертка для erlang:trace_pattern, в нескольких вариантах. Позволяет задать MatchSpec.

dbg:tp ставит флаг global, и трассирует глобальные вызовы. dbg:tpl ставит флаг local, и трассирует все вызовы.

Аргументы:

dbg:tp(Module, MatchSpec)
// тоже самое, что
erlang:trace_pattern({Module, '_', '_'}, MatchSpec, [])

dbg:tp(Module, Function, MatchSpec)
// тоже самое, что
erlang:trace_pattern({Module, Function, '_'}, MatchSpec, [])

dbg:tp(Module, Function, Arity, MatchSpec)
//тоже самое, что
erlang:trace_pattern({Module, Function, Arity}, MatchSpec, [])

Эти функции останавливают трассировку, запущенную предыдущими функциями:

• dbg:ctpg останавливает, если запущено через dbg:tp
• dbg:ctpl останавливает, если запущено через dbg:tpl
• dbg:ctp останавливает, неважно как запущено

Да, с остановкой трассировки намудрили. Мало того, что нужно совпадать по аргументам, так еще нужно помнить, какой функцией трассировка запускалась :)

Вышеуказанные функции останавливают трассировку, но не отменяют установленные флаги.

dbg:stop останавливает все трассировки, сбрасывает все флаги, закрывает порты (если был редирект событий трассировки в порты). Но не сбрасывает MatchSpec. То есть, отменяет erlang:trace но не отменяет erlang:trace_pattern

dbg:stop_clear тоже самое, плюс отменяет erlang:trace_pattern

dbg:tracer(process , {HandlerFun, Data})

Так можно задать кастомную функцию. Она должна получать 2 аргумента – событие трассировки и аккумулятор. Аргумент Data – начальное значение аккумулятора. Функция возвращает новое значение аккумулятора.

Таким образом можно организовать накопление некоторых данных в аккумуляторе. Что может пригодится, например, для анализа работы сборщика мусора, если трассируются события, связанный с его работой.

Сперва нужно получить ссылку на port function.

PortFun = dbg:trace_port(file, FileOptions)

FileOptions могут быть разными (см документацию). Например {FileName, wrap, FileSuffix} задает ротацию в файлах, аналогично, как ротируются логи.

Затем вызываем

dbg:tracer(port, PortFun)

Направить события в порт несколько сложнее. Сперва нужно получить ссылку на port function.

PortFun = dbg:trace_port(ip, Port)

Где Port – это номер порта или кортеж {PortNumber, QueueSize}.

Затем вызываем

dbg:tracer(port, PortFun)

Опция QueueSize позволяет ограничить количество сообщений, которые хранятся в буфере. Это полезно, если клиент не успевает их забирать. Лишние события будут просто игнорироваться.

На другой ноде нужно вызывать

dbg:trace_client(ip, Arg, {HandlerFun, Data})

Где Arg это номер порта или кортеж {HostName, PortNumber}

Такой клиент будет получать события из порта и обрабатывать их кастомной функцией.