<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- cprof - The Call Count Profiler</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/tools-2.6.8.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Tools</strong><br><strong>User's Guide</strong><br><small>Version 2.6.8</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="cover" expanded="false">cover<ul>
<li><a href="cover_chapter.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="cover_chapter.html#id64809">Introduction</a></li>
<li title="Getting Started With Cover"><a href="cover_chapter.html#id62638">Getting Started With Cover</a></li>
<li title="Miscellaneous"><a href="cover_chapter.html#id60749">Miscellaneous</a></li>
<li title="Using the Web Based User Interface to Cover"><a href="cover_chapter.html#id63969">Using the Web Based User Interface to Cover</a></li>
</ul>
</li>
<li id="loadscrollpos" title="cprof - The Call Count Profiler" expanded="true">cprof - The Call Count Profiler<ul>
<li><a href="cprof_chapter.html">
Top of chapter
</a></li>
<li title="Example: Background work"><a href="cprof_chapter.html#id62155">Example: Background work</a></li>
<li title="Example: One module"><a href="cprof_chapter.html#id62215">Example: One module</a></li>
<li title="Example: In the code"><a href="cprof_chapter.html#id62262">Example: In the code</a></li>
</ul>
</li>
<li id="no" title="The Erlang mode for Emacs" expanded="false">The Erlang mode for Emacs<ul>
<li><a href="erlang_mode_chapter.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="erlang_mode_chapter.html#id64082">Purpose</a></li>
<li title="Pre-requisites"><a href="erlang_mode_chapter.html#id64101">Pre-requisites</a></li>
<li title="Elisp"><a href="erlang_mode_chapter.html#id64113">Elisp</a></li>
<li title="Setup on UNIX"><a href="erlang_mode_chapter.html#id64126">Setup on UNIX</a></li>
<li title="Setup on Windows "><a href="erlang_mode_chapter.html#id64160">Setup on Windows </a></li>
<li title="Indentation"><a href="erlang_mode_chapter.html#id64228">Indentation</a></li>
<li title="Editing"><a href="erlang_mode_chapter.html#id64277">Editing</a></li>
<li title="Syntax highlighting"><a href="erlang_mode_chapter.html#id64373">Syntax highlighting</a></li>
<li title="Tags"><a href="erlang_mode_chapter.html#id64396">Tags</a></li>
<li title="Etags"><a href="erlang_mode_chapter.html#id64430">Etags</a></li>
<li title="Shell"><a href="erlang_mode_chapter.html#id64528">Shell</a></li>
<li title="Compilation"><a href="erlang_mode_chapter.html#id64585">Compilation</a></li>
</ul>
</li>
<li id="no" title="fprof - The File Trace Profiler" expanded="false">fprof - The File Trace Profiler<ul>
<li><a href="fprof_chapter.html">
Top of chapter
</a></li>
<li title="Profiling from the source code"><a href="fprof_chapter.html#id64914">Profiling from the source code</a></li>
<li title="Profiling a function"><a href="fprof_chapter.html#id64995">Profiling a function</a></li>
<li title="Immediate profiling"><a href="fprof_chapter.html#id65025">Immediate profiling</a></li>
</ul>
</li>
<li id="no" title="lcnt - The Lock Profiler" expanded="false">lcnt - The Lock Profiler<ul>
<li><a href="lcnt_chapter.html">
Top of chapter
</a></li>
<li title=" Enabling lock-counting "><a href="lcnt_chapter.html#id65145"> Enabling lock-counting </a></li>
<li title="Getting started"><a href="lcnt_chapter.html#id65194">Getting started</a></li>
<li title=" Example of usage "><a href="lcnt_chapter.html#id65262"> Example of usage </a></li>
<li title=" Example with Mnesia Transaction Benchmark "><a href="lcnt_chapter.html#id65351"> Example with Mnesia Transaction Benchmark </a></li>
<li title=" Deciphering the output "><a href="lcnt_chapter.html#id65488"> Deciphering the output </a></li>
<li title="See Also"><a href="lcnt_chapter.html#id65506">See Also</a></li>
</ul>
</li>
<li id="no" title="Xref - The Cross Reference Tool" expanded="false">Xref - The Cross Reference Tool<ul>
<li><a href="xref_chapter.html">
Top of chapter
</a></li>
<li title="Module Check"><a href="xref_chapter.html#id65613">Module Check</a></li>
<li title="Predefined Analysis"><a href="xref_chapter.html#id65693">Predefined Analysis</a></li>
<li title="Expressions"><a href="xref_chapter.html#id65996">Expressions</a></li>
<li title="Graph Analysis"><a href="xref_chapter.html#id66325">Graph Analysis</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>2 cprof - The Call Count Profiler</h1>
<p><span class="code">cprof</span> is a profiling tool that can be used to get a picture of
how often different functions in the system are called.
</p>
<p><span class="code">cprof</span> uses breakpoints similar to local call trace,
but containing counters, to collect profiling
data. Therfore there is no need for special compilation of any
module to be profiled.
</p>
<p><span class="code">cprof</span> presents all profiled modules in decreasing total
call count order, and for each module presents all profiled
functions also in decreasing call count order. A call count limit
can be specified to filter out all functions below the limit.
</p>
<p>Profiling is done in the following steps:</p>
<dl>
<dt><strong><span class="code">cprof:start/0..3</span></strong></dt>
<dd>Starts profiling with zeroed call counters for specified
functions by setting call count breakpoints on them. </dd>
<dt><strong><span class="code">Mod:Fun()</span></strong></dt>
<dd>Runs the code to be profiled.</dd>
<dt><strong><span class="code">cprof:pause/0..3</span></strong></dt>
<dd>Pauses the call counters for specified functions. This minimises
the impact of code running in the background or in the shell
that disturbs the profiling. Call counters are automatically
paused when they "hit the ceiling" of the host machine word
size. For a 32 bit host the maximum counter value is
2147483647.</dd>
<dt><strong><span class="code">cprof:analyse/0..2</span></strong></dt>
<dd>Collects call counters and computes the result.</dd>
<dt><strong><span class="code">cprof:restart/0..3</span></strong></dt>
<dd>Restarts the call counters from zero for specified
functions. Can be used to collect a new set of counters without
having to stop and start call count profiling.</dd>
<dt><strong><span class="code">cprof:stop/0..3</span></strong></dt>
<dd>Stops profiling by removing call count breakpoints from
specified functions.</dd>
</dl>
<p>Functions can be specified as either all in the system, all in one
module, all arities of one function, one function, or all
functions in all modules not yet loaded. As for now, BIFs cannot
be call count traced.
</p>
<p>The analysis result can either be for all modules, or for one
module. In either case a call count limit can be given to filter
out the functions with a call count below the limit. The all
modules analysis does <strong>not</strong> contain the module <span class="code">cprof</span>
itself, it can only be analysed by specifying it as a single
module to analyse.
</p>
<p>Call count tracing is very lightweight compared to other forms of
tracing since no trace message has to be generated. Some
measurements indicates performance degradations in the vicinity of
10 percent.
</p>
<p>The following sections show some examples of profiling with
<span class="code">cprof</span>. See also
<span class="bold_code"><a href="cprof.html">cprof(3)</a></span>.
</p>
<h3><a name="id62155">2.1
Example: Background work</a></h3>
<p>From the Erlang shell:</p>
<div class="example"><pre>
1> <span class="bold_code">cprof:start(), cprof:pause(). % Stop counters just after start</span>
3476
2> <span class="bold_code">cprof:analyse().</span>
{30,
[{erl_eval,11,
[{{erl_eval,expr,3},3},
{{erl_eval,'-merge_bindings/2-fun-0-',2},2},
{{erl_eval,expand_module_name,2},1},
{{erl_eval,merge_bindings,2},1},
{{erl_eval,binding,2},1},
{{erl_eval,expr_list,5},1},
{{erl_eval,expr_list,3},1},
{{erl_eval,exprs,4},1}]},
{orddict,8,
[{{orddict,find,2},6},
{{orddict,dict_to_list,1},1},
{{orddict,to_list,1},1}]},
{packages,7,[{{packages,is_segmented_1,1},6},
{{packages,is_segmented,1},1}]},
{lists,4,[{{lists,foldl,3},3},{{lists,reverse,1},1}]}]}
3> <span class="bold_code">cprof:analyse(cprof).</span>
{cprof,3,[{{cprof,tr,2},2},{{cprof,pause,0},1}]}
4> <span class="bold_code">cprof:stop().</span>
3476</pre></div>
<p>The example showed the background work that the shell performs
just to interpret the first command line. Most work is done by
<span class="code">erl_eval</span> and <span class="code">orddict</span>.
</p>
<p>What is captured in this example is the part of the work the
shell does while interpreting the command line that occurs
between the actual calls to <span class="code">cprof:start()</span> and
<span class="code">cprof:analyse()</span>.
</p>
<h3><a name="id62215">2.2
Example: One module</a></h3>
<p>From the Erlang shell:</p>
<div class="example"><pre>
1> <span class="bold_code">cprof:start(),R=calendar:day_of_the_week(1896,4,27),cprof:pause(),R.</span>
1
2> <span class="bold_code">cprof:analyse(calendar).</span>
{calendar,9,
[{{calendar,df,2},1},
{{calendar,dm,1},1},
{{calendar,dy,1},1},
{{calendar,last_day_of_the_month1,2},1},
{{calendar,last_day_of_the_month,2},1},
{{calendar,is_leap_year1,1},1},
{{calendar,is_leap_year,1},1},
{{calendar,day_of_the_week,3},1},
{{calendar,date_to_gregorian_days,3},1}]}
3> <span class="bold_code">cprof:stop().</span>
3271</pre></div>
<p>The example tells us that "Aktiebolaget LM Ericsson & Co"
was registered on a Monday (since the return value
of the first command is 1), and that the <span class="code">calendar</span> module
needed 9 function calls to calculate that.
</p>
<p>Using <span class="code">cprof:analyse()</span> in this example also shows
approximately the same background work as in the first example.
</p>
<h3><a name="id62262">2.3
Example: In the code</a></h3>
<p>Write a module:</p>
<div class="example"><pre>
-module(sort).
-export([do/1]).
do(N) ->
cprof:stop(),
cprof:start(),
do(N, []).
do(0, L) ->
R = lists:sort(L),
cprof:pause(),
R;
do(N, L) ->
do(N-1, [random:uniform(256)-1 | L]).</pre></div>
<p>From the Erlang shell:</p>
<div class="example"><pre>
1> <span class="bold_code">c(sort).</span>
{ok,sort}
2> <span class="bold_code">l(random).</span>
{module,random}
3> <span class="bold_code">sort:do(1000).</span>
[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|...]
4> <span class="bold_code">cprof:analyse().</span>
{9050,
[{lists_sort,6047,
[{{lists_sort,merge3_2,6},923},
{{lists_sort,merge3_1,6},879},
{{lists_sort,split_2,5},661},
{{lists_sort,rmerge3_1,6},580},
{{lists_sort,rmerge3_2,6},543},
{{lists_sort,merge3_12_3,6},531},
{{lists_sort,merge3_21_3,6},383},
{{lists_sort,split_2_1,6},338},
{{lists_sort,rmerge3_21_3,6},299},
{{lists_sort,rmerge3_12_3,6},205},
{{lists_sort,rmerge2_2,4},180},
{{lists_sort,rmerge2_1,4},171},
{{lists_sort,merge2_1,4},127},
{{lists_sort,merge2_2,4},121},
{{lists_sort,mergel,2},79},
{{lists_sort,rmergel,2},27}]},
{random,2001,
[{{random,uniform,1},1000},
{{random,uniform,0},1000},
{{random,seed0,0},1}]},
{sort,1001,[{{sort,do,2},1001}]},
{lists,1,[{{lists,sort,1},1}]}]}
5> <span class="bold_code">cprof:stop().</span>
5369</pre></div>
<p>The example shows some details of how <span class="code">lists:sort/1</span>
works. It used 6047 function calls in the module
<span class="code">lists_sort</span> to complete the work.
</p>
<p>This time, since the shell was not involved, no other work was
done in the system during the profiling. If you retry the same
example with a freshly started Erlang emulator, but omit the
command <span class="code">l(random)</span>, the analysis will show a lot more
function calls done by <span class="code">code_server</span> and others to
automatically load the module <span class="code">random</span>.
</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1508
