Compilation & Loading

To compile and launch Erlang/OTP (with the required additional arguments):

make load

Tracing

To trace a call, one should use the tracer:trace/2 or tracer:trace/3 functions.

The tracer:trace/3 functions has the following parameters:

1. InitialCall: The call to be traced in a string format (e.g., "module:fun(arg_1,...,arg_n)").
2. PidAnswer: The pid that will receive the resulting trace as a message (we often use self() here).
3. Opts: A list of options for tracing. Options can be declared using a tuple:
   • {timeout, Timeout}: The number of miliseconds that the tracer has to run for (10000 by default).
   • {dir, Dir}: The directory where the tracer has to look for modules ("." by default).
   • {log_dir, LogDir}: The directory where the tracer stores the tracing results ("trace" by default).

The tracer:trace/2 function is equivalent to tracer:trace/3 with default values.

Example

Suppose that we want to trace a call to the module tcp.erl that is in the examples/ folder and we would also like to store the results in a new folder called tcp_results/. Then, we should call the tracer as:

tracer:trace("tcp:main()", self(), [{dir,"examples"},{log_dir,"tcp_results"}]).

Note that the tcp_results/ folder is created by the tracer.

Output

Tracing a call generates a main file called trace_result.log in the logging folder and an additional file per each process spawned in the program (including the main process executing that call).

An example result file is the following:

call "acknowledge:main()"
comp "examples/acknowledge.erl" 5940
main_pid <8064.71.0>
tracing success
result ok
exec 104199

For each line, we have some information regarding the tracing input/outcome:

• call: The InitialCall argument passed to the tracer.
• comp: The compilation time (including instrumentation) of a source file in microseconds.
• main_pid: The pid of the process that executed InitialCall.
• tracing: Outcome of the tracing procedure, it can be success or timeout.
• result: Return value of InitialCall, or none if tracing timed out.
• exec: The execution time of the program in microseconds.

The remaining files trace_Pid.log include the concurrent events caused by process with pid Pid. For example, if trace_<8064.71.0>.log contains:

{71,spawn,73}
{71,send,0}
{71,'receive',1}

It means that process with pid <8064.71.0> first spawned another process with pid <8064.73.0>, then it sent a message with stamp 0, and finally it received a message with stamp 1.

Wrapping

If we are only interested in measuring standard compilation/execution times, then we can call the wrapper instead:

wrapper:trace("tcp:main()", self(), [{dir,"examples"},{log_dir,"tcp_results"}]).

The wrapper works in a similar way to the tracer (the program is executed on a separate node), but it does not trace concurrent events. Note that the {timeout, Timeout} is disabled for the wrapper. Thus, the result file will not contain the tracing outcome, and this file will be the only one generated by the wrapper.