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

NAME

DESCRIPTION

EXPORTS

SEE ALSO