Matcha
Matcha v0.1.10

View Source Tracing Cheatsheet

Get started with tracing quickly! For a more in-depth introduction to tracing, see the tracing guide.

limiting-tracing

 Limiting Tracing

Since tracing can send a lot of messages to the tracing process, several guard rails are in place by default.

However, these limits can be configured.

limiting-traced-messages

 Limiting Traced Messages

By default, all traces will be limited to a single message:

Matcha.Trace.module(Integer)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
#=> Recon tracer rate limit tripped.
Integer.parse("2")

Extend this with the :limit option:

Matcha.Trace.module(Integer, limit: 2)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
Integer.parse("2")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
#=> Recon tracer rate limit tripped.

limiting-traced-processes

 Limiting Traced Processes

By default, calls in all processes will be traced:

Matcha.Trace.module(Integer, limit: 2)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
spawn(fn -> Integer.parse("1") end)
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.320.0>

Specify which processes to trace with the :pid option:

Matcha.Trace.module(Integer, pid: :all, limit: 2)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
spawn(fn -> Integer.parse("1") end)
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.320.0>

Limit tracing to a specific process or list of processes:

Matcha.Trace.module(Integer, pid: self(), limit: 2)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
spawn(fn -> Integer.parse("1") end)

Limit tracing to just existing processes:

Matcha.Trace.module(Integer, pid: :existing, limit: 2)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>
spawn(fn -> Integer.parse("1") end)

Limit tracing to just newly spawned processes:

Matcha.Trace.module(Integer, pid: :new, limit: 2)
Integer.parse("1")
spawn(fn -> Integer.parse("1") end)
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.320.0>

tracing-calls

 Tracing Calls

tracing-calls-to-entire-modules

 Tracing Calls to Entire Modules

Use Matcha.Trace.module/1:

Matcha.Trace.module(Integer)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>

tracing-calls-to-specific-functions

 Tracing Calls to Specific Functions

Use Matcha.Trace.function/2:

Matcha.Trace.function(Integer, :parse)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>

tracing-calls-with-specific-arities

 Tracing Calls with Specific Arities

Use Matcha.Trace.calls/3 with a numeric arity:

Matcha.Trace.calls(Integer, :parse, 1)
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>

tracing-calls-with-match-specs

 Tracing Calls with Match Specs

Use the Matcha.trace_calls/3 macro:

require Matcha
Matcha.trace_calls(Integer, :parse, limit: 2) do
  ["1"] -> message("Parsing `\"1\"` into a decimal number")
  ["1", 2] -> message("Parsing `\"1\"` into a binary number")
end
Integer.parse("1")
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>: Parsing `"1"` into a decimal number
Integer.parse("1", 2)
#=> Matcha.Trace: `Elixir.Integer.parse("1")` called on #PID<0.286.0>: Parsing `"1"` into a binary number