1eprof(3)                   Erlang Module Definition                   eprof(3)
2
3
4

NAME

6       eprof - A Time Profiling Tool for Erlang
7

DESCRIPTION

9       The  module  eprof  provides  a  set of functions for time profiling of
10       Erlang programs to find out how the execution time is used. The profil‐
11       ing  is  done  using  the  Erlang trace BIFs. Tracing of local function
12       calls for a specified set of processes is  enabled  when  profiling  is
13       begun, and disabled when profiling is stopped.
14
15       When using Eprof, expect a slowdown in program execution.
16

EXPORTS

18       start() -> {ok,Pid} | {error,Reason}
19
20              Types:
21
22                 Pid = pid()
23                 Reason = {already_started,Pid}
24
25              Starts  the  Eprof  server which holds the internal state of the
26              collected data.
27
28       start_profiling(Rootset) -> profiling | {error, Reason}
29       start_profiling(Rootset,Pattern) -> profiling | {error, Reason}
30       start_profiling(Rootset,Pattern,Options) -> profiling | {error, Reason}
31
32              Types:
33
34                 Rootset = [atom() | pid()]
35                 Pattern = {Module, Function, Arity}
36                 Module = Function = atom()
37                 Arity = integer()
38                 Options = [set_on_spawn]
39                 Reason = term()
40
41              Starts profiling for the processes in Rootset (and any new  pro‐
42              cesses  spawned  from  them).  Information about activity in any
43              profiled process is stored in the Eprof database.
44
45              Rootset is a list of pids and registered names.
46
47              The function returns profiling if tracing could be  enabled  for
48              all processes in Rootset, or error otherwise.
49
50              A  pattern can be selected to narrow the profiling. For instance
51              a specific module can be selected, and only the code executed in
52              that module will be profiled.
53
54              The  set_on_spawn  option  will active call time tracing for all
55              processes spawned by processes  in  the  rootset.  This  is  the
56              default behaviour.
57
58       stop_profiling() -> profiling_stopped | profiling_already_stopped
59
60              Stops profiling started with start_profiling/1 or profile/1.
61
62       profile(Fun) -> profiling | {error, Reason}
63       profile(Fun, Options) -> profiling | {error, Reason}
64       profile(Rootset) -> profiling | {error, Reason}
65       profile(Rootset,Fun) -> {ok, Value} | {error,Reason}
66       profile(Rootset,Fun,Pattern) -> {ok, Value} | {error, Reason}
67       profile(Rootset,Module,Function,Args) -> {ok, Value} | {error, Reason}
68       profile(Rootset,Module,Function,Args,Pattern)  -> {ok, Value} | {error,
69       Reason}
70       profile(Rootset,Module,Function,Args,Pattern,Options) -> {ok, Value}  |
71       {error, Reason}
72
73              Types:
74
75                 Rootset = [atom() | pid()]
76                 Fun = fun() -> term() end
77                 Pattern = {Module, Function, Arity}
78                 Module = Function = atom()
79                 Args = [term()]
80                 Arity = integer()
81                 Options = [set_on_spawn]
82                 Value = Reason = term()
83
84              This  function first spawns a process P which evaluates Fun() or
85              apply(Module,Function,Args). Then, it starts profiling for P and
86              the  processes  in  Rootset  (and any new processes spawned from
87              them). Information about activity in  any  profiled  process  is
88              stored in the Eprof database.
89
90              Rootset is a list of pids and registered names.
91
92              If  tracing could be enabled for P and all processes in Rootset,
93              the function returns {ok,Value} when  Fun()/apply  returns  with
94              the  value  Value,  or  {error,Reason} if Fun()/apply fails with
95              exit reason Reason. Otherwise it returns {error, Reason} immedi‐
96              ately.
97
98              The  set_on_spawn  option  will active call time tracing for all
99              processes spawned by processes  in  the  rootset.  This  is  the
100              default behaviour.
101
102              The  programmer  must ensure that the function given as argument
103              is truly synchronous and that no work continues after the  func‐
104              tion has returned a value.
105
106       analyze() -> ok
107       analyze(Type) -> ok
108       analyze(Type,Options) -> ok
109
110              Types:
111
112                 Type = procs | total
113                 Options = [{filter, Filter} | {sort, Sort}
114                 Filter = [{calls, integer()} | {time, float()}]
115                 Sort = time | calls | mfa
116
117              Call  this  function  when profiling has been stopped to display
118              the results per process, that is:
119
120                * how much time has been used by each process, and
121
122                * in which function calls this time has been spent.
123
124              Call analyze with total option when profiling has  been  stopped
125              to display the results per function call, that is in which func‐
126              tion calls the time has been spent.
127
128              Time is shown as percentage of total time and as absolute time.
129
130       log(File) -> ok
131
132              Types:
133
134                 File = atom() | string()
135
136              This  function  ensures  that  the  results  displayed  by  ana‐
137              lyze/0,1,2 are printed both to the file File and the screen.
138
139       stop() -> stopped
140
141              Stops the Eprof server.
142
143
144
145Ericsson AB                      tools 3.1.0.1                        eprof(3)