cprof(3erl)

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

NAME

6       cprof  - A simple Call Count Profiling Tool using breakpoints for mini‐
7       mal runtime performance impact.
8

DESCRIPTION

10       The cprof module is used to profile a program  to  find  out  how  many
11       times different functions are called. Breakpoints similar to local call
12       trace, but containing a counter, are used to minimise  runtime  perfor‐
13       mance impact.
14
15       Since  breakpoints are used there is no need for special compilation of
16       any module to be profiled. For now these breakpoints can only be set on
17       BEAM code so BIFs cannot be call count traced.
18
19       The size of the call counters is the host machine word size. One bit is
20       used when pausing the counter, so  the  maximum  counter  value  for  a
21       32-bit host is 2147483647.
22
23       The profiling result is delivered as a term containing a sorted list of
24       entries, one per module. Each module entry contains a  sorted  list  of
25       functions. The sorting order in both cases is of decreasing call count.
26
27       Call count tracing is very lightweight compared to other forms of trac‐
28       ing since no trace message has to be generated. Some measurements indi‐
29       cates performance degradation in the vicinity of 10 percent.
30

EXPORTS

32       analyse() -> {AllCallCount, ModAnalysisList}
33       analyse(Limit) -> {AllCallCount, ModAnalysisList}
34       analyse(Mod) -> ModAnalysis
35       analyse(Mod, Limit) -> ModAnalysis
36
37              Types:
38
39                 Limit = integer()
40                 Mod = atom()
41                 AllCallCount = integer()
42                 ModAnalysisList = [ModAnalysis]
43                 ModAnalysis = {Mod, ModCallCount, FuncAnalysisList}
44                 ModCallCount = integer()
45                 FuncAnalysisList = [{{Mod, Func, Arity}, FuncCallCount}]
46                 Func = atom()
47                 Arity = integer()
48                 FuncCallCount = integer()
49
50              Collects  and  analyses  the call counters presently in the node
51              for either module Mod, or for all modules (except cprof itself),
52              and returns:
53
54                FuncAnalysisList:
55                  A  list  of  tuples,  one  for each function in a module, in
56                  decreasing FuncCallCount order.
57
58                ModCallCount:
59                  The sum of FuncCallCount values for all functions in  module
60                  Mod.
61
62                AllCallCount:
63                  The  sum of ModCallCount values for all modules concerned in
64                  ModAnalysisList.
65
66                ModAnalysisList:
67                  A list of tuples, one  for  each  module  except  cprof,  in
68                  decreasing ModCallCount order.
69
70              If call counters are still running while analyse/0..2 is execut‐
71              ing, you might get an inconsistent result. This happens  if  the
72              process  executing analyse/0..2 gets scheduled out so some other
73              process can increment the  counters  that  are  being  analysed,
74              Calling pause() before analysing takes care of the problem.
75
76              If  the Mod argument is given, the result contains a ModAnalysis
77              tuple for module Mod only, otherwise  the  result  contains  one
78              ModAnalysis    tuple    for    all    modules    returned   from
79              code:all_loaded() except cprof itself.
80
81              All functions with a FuncCallCount lower than Limit are excluded
82              from  FuncAnalysisList. They are still included in ModCallCount,
83              though. The default value for Limit is 1.
84
85       pause() -> integer()
86
87              Pause call count tracing for all functions in  all  modules  and
88              stop  it  for all functions in modules to be loaded. This is the
89              same as (pause({'_','_','_'})+stop({on_load})).
90
91              See also pause/1..3 below.
92
93       pause(FuncSpec) -> integer()
94       pause(Mod, Func) -> integer()
95       pause(Mod, Func, Arity) -> integer()
96
97              Types:
98
99                 FuncSpec = Mod | {Mod,Func,Arity}, {FS}
100                 Mod = atom()
101                 Func = atom()
102                 Arity = integer()
103                 FS = term()
104
105              Pause call counters for matching functions in matching  modules.
106              The  FS  argument  can  be used to specify the first argument to
107              erlang:trace_pattern/3. See erlang(3).
108
109              The call counters for all matching functions that has  got  call
110              count breakpoints are paused at their current count.
111
112              Return the number of matching functions that can have call count
113              breakpoints, the same as  start/0..3  with  the  same  arguments
114              would have returned.
115
116       restart() -> integer()
117       restart(FuncSpec) -> integer()
118       restart(Mod, Func) -> integer()
119       restart(Mod, Func, Arity) -> integer()
120
121              Types:
122
123                 FuncSpec = Mod | {Mod,Func,Arity}, {FS}
124                 Mod = atom()
125                 Func = atom()
126                 Arity = integer()
127                 FS = term()
128
129              Restart  call  counters  for  the matching functions in matching
130              modules that are call count traced. The FS argument can be  used
131              to  specify  the  first  argument to erlang:trace_pattern/3. See
132              erlang(3).
133
134              The call counters for all matching functions that has  got  call
135              count breakpoints are set to zero and running.
136
137              Return the number of matching functions that can have call count
138              breakpoints, the same as  start/0..3  with  the  same  arguments
139              would have returned.
140
141       start() -> integer()
142
143              Start  call  count tracing for all functions in all modules, and
144              also for all functions in modules to be loaded. This is the same
145              as (start({'_','_','_'})+start({on_load})).
146
147              See also start/1..3 below.
148
149       start(FuncSpec) -> integer()
150       start(Mod, Func) -> integer()
151       start(Mod, Func, Arity) -> integer()
152
153              Types:
154
155                 FuncSpec = Mod | {Mod,Func,Arity}, {FS}
156                 Mod = atom()
157                 Func = atom()
158                 Arity = integer()
159                 FS = term()
160
161              Start call count tracing for matching functions in matching mod‐
162              ules. The FS argument can be used to specify the first  argument
163              to erlang:trace_pattern/3, for example on_load. See erlang(3).
164
165              Set call count breakpoints on the matching functions that has no
166              call count breakpoints. Call counters are set to zero  and  run‐
167              ning for all matching functions.
168
169              Return  the number of matching functions that has got call count
170              breakpoints.
171
172       stop() -> integer()
173
174              Stop call count tracing for all functions in  all  modules,  and
175              also for all functions in modules to be loaded. This is the same
176              as (stop({'_','_','_'})+stop({on_load})).
177
178              See also stop/1..3 below.
179
180       stop(FuncSpec) -> integer()
181       stop(Mod, Func) -> integer()
182       stop(Mod, Func, Arity) -> integer()
183
184              Types:
185
186                 FuncSpec = Mod | {Mod,Func,Arity}, {FS}
187                 Mod = atom()
188                 Func = atom()
189                 Arity = integer()
190                 FS = term()
191
192              Stop call count tracing for matching functions in matching  mod‐
193              ules.  The FS argument can be used to specify the first argument
194              to erlang:trace_pattern/3, for example on_load. See erlang(3).
195
196              Remove call count breakpoints from the matching  functions  that
197              has call count breakpoints.
198
199              Return the number of matching functions that can have call count
200              breakpoints, the same as  start/0..3  with  the  same  arguments
201              would have returned.
202

NAME

DESCRIPTION

EXPORTS

SEE ALSO