1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE chapter SYSTEM "chapter.dtd"> 3 4<chapter> 5 <header> 6 <copyright> 7 <year>2002</year><year>2016</year> 8 <holder>Ericsson AB. All Rights Reserved.</holder> 9 </copyright> 10 <legalnotice> 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 23 </legalnotice> 24 25 <title>cprof - The Call Count Profiler</title> 26 <prepared>Raimo Niskanen</prepared> 27 <responsible>nobody</responsible> 28 <docno></docno> 29 <approved>nobody</approved> 30 <checked>no</checked> 31 <date>2002-09-11</date> 32 <rev>PA1</rev> 33 <file>cprof_chapter.xml</file> 34 </header> 35 <p><c>cprof</c> is a profiling tool that can be used to get a picture of 36 how often different functions in the system are called. 37 </p> 38 <p><c>cprof</c> uses breakpoints similar to local call trace, 39 but containing counters, to collect profiling 40 data. Therfore there is no need for special compilation of any 41 module to be profiled. 42 </p> 43 <p><c>cprof</c> presents all profiled modules in decreasing total 44 call count order, and for each module presents all profiled 45 functions also in decreasing call count order. A call count limit 46 can be specified to filter out all functions below the limit. 47 </p> 48 <p>Profiling is done in the following steps:</p> 49 <taglist> 50 <tag><c>cprof:start/0..3</c></tag> 51 <item>Starts profiling with zeroed call counters for specified 52 functions by setting call count breakpoints on them. </item> 53 <tag><c>Mod:Fun()</c></tag> 54 <item>Runs the code to be profiled.</item> 55 <tag><c>cprof:pause/0..3</c></tag> 56 <item>Pauses the call counters for specified functions. This minimises 57 the impact of code running in the background or in the shell 58 that disturbs the profiling. Call counters are automatically 59 paused when they "hit the ceiling" of the host machine word 60 size. For a 32 bit host the maximum counter value is 61 2147483647.</item> 62 <tag><c>cprof:analyse/0..2</c></tag> 63 <item>Collects call counters and computes the result.</item> 64 <tag><c>cprof:restart/0..3</c></tag> 65 <item>Restarts the call counters from zero for specified 66 functions. Can be used to collect a new set of counters without 67 having to stop and start call count profiling.</item> 68 <tag><c>cprof:stop/0..3</c></tag> 69 <item>Stops profiling by removing call count breakpoints from 70 specified functions.</item> 71 </taglist> 72 <p>Functions can be specified as either all in the system, all in one 73 module, all arities of one function, one function, or all 74 functions in all modules not yet loaded. As for now, BIFs cannot 75 be call count traced. 76 </p> 77 <p>The analysis result can either be for all modules, or for one 78 module. In either case a call count limit can be given to filter 79 out the functions with a call count below the limit. The all 80 modules analysis does <em>not</em> contain the module <c>cprof</c> 81 itself, it can only be analysed by specifying it as a single 82 module to analyse. 83 </p> 84 <p>Call count tracing is very lightweight compared to other forms of 85 tracing since no trace message has to be generated. Some 86 measurements indicates performance degradations in the vicinity of 87 10 percent. 88 </p> 89 <p>The following sections show some examples of profiling with 90 <c>cprof</c>. See also 91 <seealso marker="cprof">cprof(3)</seealso>. 92 </p> 93 94 <section> 95 <title>Example: Background work</title> 96 <p>From the Erlang shell:</p> 97 <pre> 981> <input>cprof:start(), cprof:pause(). % Stop counters just after start</input> 993476 1002> <input>cprof:analyse().</input> 101{30, 102 [{erl_eval,11, 103 [{{erl_eval,expr,3},3}, 104 {{erl_eval,'-merge_bindings/2-fun-0-',2},2}, 105 {{erl_eval,expand_module_name,2},1}, 106 {{erl_eval,merge_bindings,2},1}, 107 {{erl_eval,binding,2},1}, 108 {{erl_eval,expr_list,5},1}, 109 {{erl_eval,expr_list,3},1}, 110 {{erl_eval,exprs,4},1}]}, 111 {orddict,8, 112 [{{orddict,find,2},6}, 113 {{orddict,dict_to_list,1},1}, 114 {{orddict,to_list,1},1}]}, 115 {packages,7,[{{packages,is_segmented_1,1},6}, 116 {{packages,is_segmented,1},1}]}, 117 {lists,4,[{{lists,foldl,3},3},{{lists,reverse,1},1}]}]} 1183> <input>cprof:analyse(cprof).</input> 119{cprof,3,[{{cprof,tr,2},2},{{cprof,pause,0},1}]} 1204> <input>cprof:stop().</input> 1213476</pre> 122 <p>The example showed the background work that the shell performs 123 just to interpret the first command line. Most work is done by 124 <c>erl_eval</c> and <c>orddict</c>. 125 </p> 126 <p>What is captured in this example is the part of the work the 127 shell does while interpreting the command line that occurs 128 between the actual calls to <c>cprof:start()</c> and 129 <c>cprof:analyse()</c>. 130 </p> 131 </section> 132 133 <section> 134 <title>Example: One module</title> 135 <p>From the Erlang shell:</p> 136 <pre> 1371> <input>cprof:start(),R=calendar:day_of_the_week(1896,4,27),cprof:pause(),R.</input> 1381 1392> <input>cprof:analyse(calendar).</input> 140{calendar,9, 141 [{{calendar,df,2},1}, 142 {{calendar,dm,1},1}, 143 {{calendar,dy,1},1}, 144 {{calendar,last_day_of_the_month1,2},1}, 145 {{calendar,last_day_of_the_month,2},1}, 146 {{calendar,is_leap_year1,1},1}, 147 {{calendar,is_leap_year,1},1}, 148 {{calendar,day_of_the_week,3},1}, 149 {{calendar,date_to_gregorian_days,3},1}]} 1503> <input>cprof:stop().</input> 1513271</pre> 152 <p>The example tells us that "Aktiebolaget LM Ericsson & Co" 153 was registered on a Monday (since the return value 154 of the first command is 1), and that the <c>calendar</c> module 155 needed 9 function calls to calculate that. 156 </p> 157 <p>Using <c>cprof:analyse()</c> in this example also shows 158 approximately the same background work as in the first example. 159 </p> 160 </section> 161 162 <section> 163 <title>Example: In the code</title> 164 <p>Write a module:</p> 165 <pre> 166-module(sort). 167 168-export([do/1]). 169 170do(N) -> 171 cprof:stop(), 172 cprof:start(), 173 do(N, []). 174 175do(0, L) -> 176 R = lists:sort(L), 177 cprof:pause(), 178 R; 179do(N, L) -> 180 do(N-1, [random:uniform(256)-1 | L]).</pre> 181 <p>From the Erlang shell:</p> 182 <pre> 1831> <input>c(sort).</input> 184{ok,sort} 1852> <input>l(random).</input> 186{module,random} 1873> <input>sort:do(1000).</input> 188[0,0,1,1,1,1,1,1,2,2,2,3,3,3,3,3,4,4,4,5,5,5,5,6,6,6,6,6,6|...] 1894> <input>cprof:analyse().</input> 190{9050, 191 [{lists_sort,6047, 192 [{{lists_sort,merge3_2,6},923}, 193 {{lists_sort,merge3_1,6},879}, 194 {{lists_sort,split_2,5},661}, 195 {{lists_sort,rmerge3_1,6},580}, 196 {{lists_sort,rmerge3_2,6},543}, 197 {{lists_sort,merge3_12_3,6},531}, 198 {{lists_sort,merge3_21_3,6},383}, 199 {{lists_sort,split_2_1,6},338}, 200 {{lists_sort,rmerge3_21_3,6},299}, 201 {{lists_sort,rmerge3_12_3,6},205}, 202 {{lists_sort,rmerge2_2,4},180}, 203 {{lists_sort,rmerge2_1,4},171}, 204 {{lists_sort,merge2_1,4},127}, 205 {{lists_sort,merge2_2,4},121}, 206 {{lists_sort,mergel,2},79}, 207 {{lists_sort,rmergel,2},27}]}, 208 {random,2001, 209 [{{random,uniform,1},1000}, 210 {{random,uniform,0},1000}, 211 {{random,seed0,0},1}]}, 212 {sort,1001,[{{sort,do,2},1001}]}, 213 {lists,1,[{{lists,sort,1},1}]}]} 2145> <input>cprof:stop().</input> 2155369</pre> 216 <p>The example shows some details of how <c>lists:sort/1</c> 217 works. It used 6047 function calls in the module 218 <c>lists_sort</c> to complete the work. 219 </p> 220 <p>This time, since the shell was not involved, no other work was 221 done in the system during the profiling. If you retry the same 222 example with a freshly started Erlang emulator, but omit the 223 command <c>l(random)</c>, the analysis will show a lot more 224 function calls done by <c>code_server</c> and others to 225 automatically load the module <c>random</c>. 226 </p> 227 </section> 228</chapter> 229 230