View Source Entrace (Entrace v0.1.1)

Base module for starting a GenServer that performs tracing.

Typically you would rather add a module to your project that uses the Entrace.Tracer.

defmodule MyApp.Tracer do
  use Entrace.Tracer
end

And in your application.ex list of children to supervise add:

MyApp.Tracer

It will run as locally registered on it's module name (in this case MyApp.Tracer).

It is not useful to run multiple Tracer instances as the Erlang tracing facility has some limits around how many tracers you can operate.

Summary

Types

mfa_pattern()

trace_error()

trace_result()

tracer()

transmission()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

list_trace_info(tracer)

Get a map of trace info for function calls based on patterns.

list_trace_patterns(tracer)

Get map of trace patterns.

start_link(opts \\ [])

Starts the Tracer linked to the parent process.

stop(tracer, mfa)

Stop tracing the mfa pattern.

trace(tracer, mfa, transmission, opts \\ [])

Start a trace for a provided pattern and transmission mechanism.

trace_cluster(tracer, mfa, transmission, opts \\ [])

Start a trace across the entire cluster.

Types

mfa_pattern()

@type mfa_pattern() :: {atom(), atom(), atom() | non_neg_integer()}

trace_error()

@type trace_error() :: {:covered_already, mfa_pattern()} | :full_wildcard_rejected

trace_result()

@type trace_result() ::
  {:set, non_neg_integer()} | {:reset_existing, non_neg_integer()}

tracer()

@type tracer() :: GenServer.server()

transmission()

@type transmission() :: function() | pid() | mfa()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

list_trace_info(tracer)

@spec list_trace_info(tracer :: tracer()) :: map()

Get a map of trace info for function calls based on patterns.

The map is keyed by mfas that have been seen during the trace. Trace info includes information from :erlang.trace_info/2. It includes :call_count, :call_memory and :call_time.

list_trace_patterns(tracer)

@spec list_trace_patterns(tracer :: tracer()) :: map()

Get map of trace patterns.

This should be tidied up, exposes a bit much in terms of internals.

start_link(opts \\ [])

Starts the Tracer linked to the parent process.

Operations can then be performed on the resulting pid or registered name.

All options are passed along to the GenServer.start_link. There is no configuration for the tracer.

stop(tracer, mfa)

@spec stop(tracer :: tracer(), mfa :: mfa_pattern()) :: :ok

Stop tracing the mfa pattern.

trace(tracer, mfa, transmission, opts \\ [])

@spec trace(
  tracer :: tracer(),
  mfa :: mfa_pattern(),
  transmission :: transmission(),
  opts :: keyword()
) :: {:ok, trace_result()} | {:error, trace_error()}

Start a trace for a provided pattern and transmission mechanism.

The pattern is an mfa tuple, as in {module, function, arity}. For example {File, read, 1} to trace the File.read/1 function. It supports a special underscore atom :_ to indicate a wilcard in the mfa. You can only use wildcards on the function and arity and Erlang's tracing only allows wildcard function if the arity is also a wildcard.

The transmission is one of:

a PID to send traces to.
a callback function.
a callback function provided as {module, function, arity}

Optional options are available. The options are:

limit - the maximum number of messages to process before ending the trace on that pattern. Default limit is 200.
time_limit - time to leave the trace running. If no limit is specified this will use a larger default limit of 10_000.

Returns information about how setting the trace pattern worked out.

trace_cluster(tracer, mfa, transmission, opts \\ [])

@spec trace_cluster(
  tracer :: tracer(),
  mfa :: mfa_pattern(),
  transmission :: transmission(),
  opts :: keyword()
) :: [ok: trace_result(), error: trace_error()]

Start a trace across the entire cluster.

See Entrace.trace/4 for details on arguments.