.TH eprof 3erl "tools 3.4.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
.B
start() -> {ok,Pid} | {error,Reason}
.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
.B
start_profiling(Rootset) -> profiling | {error, Reason}
.br
.B
start_profiling(Rootset,Pattern) -> profiling | {error, Reason}
.br
.B
start_profiling(Rootset,Pattern,Options) -> profiling | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Rootset = [atom() | pid()]
.br
Pattern = {Module, Function, Arity}
.br
Module = Function = atom()
.br
Arity = integer()
.br
Options = [set_on_spawn]
.br
Reason = term()
.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
.B
stop_profiling() -> profiling_stopped | profiling_already_stopped
.br
.RS
.LP
Stops profiling started with \fIstart_profiling/1\fR\& or \fIprofile/1\fR\&\&.
.RE

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

.RS 3
Rootset = [atom() | pid()]
.br
Fun = fun() -> term() end
.br
Pattern = {Module, Function, Arity}
.br
Module = Function = atom()
.br
Args = [term()]
.br
Arity = integer()
.br
Options = [set_on_spawn]
.br
Value = Reason = term()
.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
.B
analyze() -> ok
.br
.B
analyze(Type) -> ok
.br
.B
analyze(Type,Options) -> ok
.br
.RS
.LP
Types:

.RS 3
Type = procs | total
.br
Options = [{filter, Filter} | {sort, Sort}
.br
Filter = [{calls, integer()} | {time, float()}]
.br
Sort = time | calls | mfa
.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
.B
log(File) -> ok
.br
.RS
.LP
Types:

.RS 3
File = atom() | string()
.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
.B
stop() -> stopped
.br
.RS
.LP
Stops the Eprof server\&.
.RE