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 Er‐
10       lang programs to find out how the execution time is used. The profiling
11       is  done  using  the Erlang trace BIFs. Tracing of local function calls
12       for a specified set of processes is enabled when  profiling  is  begun,
13       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
30       start_profiling(Rootset, Pattern) -> profiling | {error, Reason}
31
32       start_profiling(Rootset, Pattern, Options) ->
33                          profiling | {error, Reason}
34
35              Types:
36
37                 Rootset = [atom() | pid()]
38                 Pattern = trace_pattern_mfa()
39                 Options = [set_on_spawn | {set_on_spawn, boolean()}]
40                 Reason = term()
41                 trace_pattern_mfa() = {atom(), atom(), arity() | '_'}
42
43              Starts profiling for the processes in Rootset (and any new  pro‐
44              cesses  spawned  from  them).  Information about activity in any
45              profiled process is stored in the Eprof database.
46
47              Rootset is a list of pids and registered names.
48
49              The function returns profiling if tracing could be  enabled  for
50              all processes in Rootset, or error otherwise.
51
52              A  pattern can be selected to narrow the profiling. For instance
53              a specific module can be selected, and only the code executed in
54              that module will be profiled.
55
56              The  set_on_spawn  option  will active call time tracing for all
57              processes spawned by processes in the rootset. This is  the  de‐
58              fault behaviour.
59
60       stop_profiling() -> profiling_stopped | profiling_already_stopped
61
62              Stops profiling started with start_profiling/1 or prifile/1.
63
64       profile(Fun) -> {ok, Value} | {error, Reason}
65
66       profile(Fun, Options) -> {ok, Value} | {error, Reason}
67
68       profile(Rootset) -> profiling | {error, Reason}
69
70       profile(Rootset, Fun) -> {ok, Value} | {error, Reason}
71
72       profile(Rootset, Fun, Pattern) -> {ok, Value} | {error, Reason}
73
74       profile(Rootset, Module, Function, Args) ->
75                  {ok, Value} | {error, Reason}
76
77       profile(Rootset, Fun, Pattern, Options) ->
78                  {ok, Value} | {error, Reason}
79
80       profile(Rootset, Module, Function, Args, Pattern) ->
81                  {ok, Value} | {error, Reason}
82
83       profile(Rootset, Module, Function, Args, Pattern, Options) ->
84                  {ok, Value} | {error, Reason}
85
86              Types:
87
88                 Rootset = [atom() | pid()]
89                 Module = module()
90                 Function = atom()
91                 Args = [term()]
92                 Pattern = trace_pattern_mfa()
93                 Options = [set_on_spawn | {set_on_spawn, boolean()}]
94                 Value = Reason = term()
95                 trace_pattern_mfa() = {atom(), atom(), arity() | '_'}
96
97              This  function first spawns a process P which evaluates Fun() or
98              apply(Module,Function,Args). Then, it starts profiling for P and
99              the  processes  in  Rootset  (and any new processes spawned from
100              them). Information about activity in  any  profiled  process  is
101              stored in the Eprof database.
102
103              Rootset is a list of pids and registered names.
104
105              If  tracing could be enabled for P and all processes in Rootset,
106              the function returns {ok,Value} when  Fun()/apply  returns  with
107              the  value  Value,  or  {error,Reason} if Fun()/apply fails with
108              exit reason Reason. Otherwise it returns {error, Reason} immedi‐
109              ately.
110
111              The  set_on_spawn  option  will active call time tracing for all
112              processes spawned by processes in the rootset. This is  the  de‐
113              fault behaviour.
114
115              The  programmer  must ensure that the function given as argument
116              is truly synchronous and that no work continues after the  func‐
117              tion has returned a value.
118
119       analyze() -> ok | nothing_to_analyze
120
121       analyze(Type) -> ok | nothing_to_analyze
122
123       analyze(Type, Options) -> ok | nothing_to_analyze
124
125              Types:
126
127                 Type = analyze_type()
128                 Options = [Option]
129                 Option = {filter, Filter} | {sort, Sort}
130                 Filter = [{calls, integer() >= 0} | {time, float()}]
131                 Sort = time | calls | mfa
132                 analyze_type() = procs | total
133
134              Call  this  function  when profiling has been stopped to display
135              the results per process, that is:
136
137                * how much time has been used by each process, and
138
139                * in which function calls this time has been spent.
140
141              Call analyze with total option when profiling has  been  stopped
142              to display the results per function call, that is in which func‐
143              tion calls the time has been spent.
144
145              Time is shown as percentage of total time and as absolute time.
146
147       log(File) -> ok
148
149              Types:
150
151                 File = atom() | file:filename()
152
153              This  function  ensures  that  the  results  displayed  by  ana‐
154              lyze/0,1,2 are printed both to the file File and the screen.
155
156       stop() -> stopped
157
158              Stops the Eprof server.
159
160
161
162Ericsson AB                       tools 3.5.1                         eprof(3)