Traces calls, return values and exceptions from the function call template given as an argument.

The template names a module, a function and its arguments. An argument is either _, which matches any value, or a value that the argument must equal. Only the template's arity is traced. Raises UndefinedFunctionError if the function does not exist.

Each event is printed to the group leader of the calling process. Returns the number of traced functions.

A trace stops, and prints the reason, when the limit is reached or when its owner exits. A trace started at the shell prompt belongs to the shell, so errors in the shell do not stop it. A trace started in any other process belongs to that process.

Options

opts is a keyword list, or an integer as a shorthand for limit:.

• :limit - the number of events after which the trace stops, a positive integer. A call and its return value or exception are two events. Defaults to 2.
• :pid - the processes to trace: a pid, a non-empty list of pids, :all, :new or :existing. Defaults to :all. Raises if a single pid is dead or on another node. A list skips such pids, prints a line for each, and raises if none is left.
• :scope - :global traces only fully qualified calls, :local also traces local calls. Defaults to :global.

Examples

Trace calls to &String.starts_with?/2 and print the first two events:

iex> Tap.call(String.starts_with?(_, _), 2)
1

Trace calls to &String.starts_with?/2 when the second argument is "b" and print the first event:

iex> Tap.call(String.starts_with?(_, "b"), limit: 1)
1

Trace calls from the current process only:

iex> Tap.call(String.starts_with?(_, _), pid: self())
1