.TH eprof 3erl "tools 3.5.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
eprof \- A Time Profiling Tool for Erlang
.SH DESCRIPTION
.LP
The module \fIeprof\fR\& provides a set of functions for time profiling of Erlang programs to find out how the execution time is used\&. The profiling is done using the Erlang trace BIFs\&. Tracing of local function calls for a specified set of processes is enabled when profiling is begun, and disabled when profiling is stopped\&.
.LP
When using Eprof, expect a slowdown in program execution\&.
.SH EXPORTS
.LP
.nf

.B
start() -> {ok, Pid} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Pid = pid()
.br
Reason = {already_started, Pid}
.br
.RE
.RE
.RS
.LP
Starts the Eprof server which holds the internal state of the collected data\&.
.RE

.LP
.nf

.B
start_profiling(Rootset) -> profiling | {error, Reason}
.br
.fi
.br
.nf

.B
start_profiling(Rootset, Pattern) -> profiling | {error, Reason}
.br
.fi
.br
.nf

.B
start_profiling(Rootset, Pattern, Options) ->
.B
                   profiling | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Rootset = [atom() | pid()]
.br
Pattern = trace_pattern_mfa()
.br
Options = [set_on_spawn | {set_on_spawn, boolean()}]
.br
Reason = term()
.br
.nf
\fBtrace_pattern_mfa()\fR\& = {atom(), atom(), arity() | \&'_\&'}
.fi
.br
.RE
.RE
.RS
.LP
Starts profiling for the processes in \fIRootset\fR\& (and any new processes spawned from them)\&. Information about activity in any profiled process is stored in the Eprof database\&.
.LP
\fIRootset\fR\& is a list of pids and registered names\&.
.LP
The function returns \fIprofiling\fR\& if tracing could be enabled for all processes in \fIRootset\fR\&, or \fIerror\fR\& otherwise\&.
.LP
A pattern can be selected to narrow the profiling\&. For instance a specific module can be selected, and only the code executed in that module will be profiled\&.
.LP
The \fIset_on_spawn\fR\& option will active call time tracing for all processes spawned by processes in the rootset\&. This is the default behaviour\&.
.RE

.LP
.nf

.B
stop_profiling() -> profiling_stopped | profiling_already_stopped
.br
.fi
.br
.RS
.LP
Stops profiling started with \fIstart_profiling/1\fR\& or \fIprofile/1\fR\&\&.
.RE

.LP
.nf

.B
profile(Fun) -> {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Fun, Options) -> {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset) -> profiling | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Fun) -> {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Fun, Pattern) -> {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Module, Function, Args) ->
.B
           {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Fun, Pattern, Options) ->
.B
           {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Module, Function, Args, Pattern) ->
.B
           {ok, Value} | {error, Reason}
.br
.fi
.br
.nf

.B
profile(Rootset, Module, Function, Args, Pattern, Options) ->
.B
           {ok, Value} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Rootset = [atom() | pid()]
.br
Module = module()
.br
Function = atom()
.br
Args = [term()]
.br
Pattern = trace_pattern_mfa()
.br
Options = [set_on_spawn | {set_on_spawn, boolean()}]
.br
Value = Reason = term()
.br
.nf
\fBtrace_pattern_mfa()\fR\& = {atom(), atom(), arity() | \&'_\&'}
.fi
.br
.RE
.RE
.RS
.LP
This function first spawns a process \fIP\fR\& which evaluates \fIFun()\fR\& or \fIapply(Module,Function,Args)\fR\&\&. Then, it starts profiling for \fIP\fR\& and the processes in \fIRootset\fR\& (and any new processes spawned from them)\&. Information about activity in any profiled process is stored in the Eprof database\&.
.LP
\fIRootset\fR\& is a list of pids and registered names\&.
.LP
If tracing could be enabled for \fIP\fR\& and all processes in \fIRootset\fR\&, the function returns \fI{ok,Value}\fR\& when \fIFun()\fR\&/\fIapply\fR\& returns with the value \fIValue\fR\&, or \fI{error,Reason}\fR\& if \fIFun()\fR\&/\fIapply\fR\& fails with exit reason \fIReason\fR\&\&. Otherwise it returns \fI{error, Reason}\fR\& immediately\&.
.LP
The \fIset_on_spawn\fR\& option will active call time tracing for all processes spawned by processes in the rootset\&. This is the default behaviour\&.
.LP
The programmer must ensure that the function given as argument is truly synchronous and that no work continues after the function has returned a value\&.
.RE

.LP
.nf

.B
analyze() -> ok | nothing_to_analyze
.br
.fi
.br
.nf

.B
analyze(Type) -> ok | nothing_to_analyze
.br
.fi
.br
.nf

.B
analyze(Type, Options) -> ok | nothing_to_analyze
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = analyze_type()
.br
Options = [Option]
.br
Option = {filter, Filter} | {sort, Sort}
.br
Filter = [{calls, integer() >= 0} | {time, float()}]
.br
Sort = time | calls | mfa
.br
.nf
\fBanalyze_type()\fR\& = procs | total
.fi
.br
.RE
.RE
.RS
.LP
Call this function when profiling has been stopped to display the results per process, that is:
.RS 2
.TP 2
*
how much time has been used by each process, and
.LP
.TP 2
*
in which function calls this time has been spent\&.
.LP
.RE

.LP
Call \fIanalyze\fR\& with \fItotal\fR\& option when profiling has been stopped to display the results per function call, that is in which function calls the time has been spent\&.
.LP
Time is shown as percentage of total time and as absolute time\&.
.RE

.LP
.nf

.B
log(File) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
File = atom() | file:filename()
.br
.RE
.RE
.RS
.LP
This function ensures that the results displayed by \fIanalyze/0,1,2\fR\& are printed both to the file \fIFile\fR\& and the screen\&.
.RE

.LP
.nf

.B
stop() -> stopped
.br
.fi
.br
.RS
.LP
Stops the Eprof server\&.
.RE