1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>fprof - The File Trace Profiler</title>
27
<prepared>Raimo Niskanen</prepared>
28
<responsible>nobody</responsible>
30
<approved>nobody</approved>
32
<date>2001-08-14</date>
34
<file>fprof_chapter.sgml</file>
36
<p><c>fprof</c> is a profiling tool that can be used to get a picture of
37
how much processing time different functions consumes and in which
40
<p><c>fprof</c> uses tracing with timestamps to collect profiling
41
data. Therfore there is no need for special compilation of any
42
module to be profiled.
44
<p><c>fprof</c> presents wall clock times from the host machine OS,
45
with the assumption that OS scheduling will randomly load the
46
profiled functions in a fair way. Both <em>own time</em> i.e the
47
time used by a function for its own execution, and
48
<em>accumulated time</em> i.e execution time including called
51
<p>Profiling is essentially done in 3 steps:</p>
54
<item>Tracing; to file, as mentioned in the previous paragraph.</item>
56
<item>Profiling; the trace file is read and raw profile data is
57
collected into an internal RAM storage on the node. During
58
this step the trace data may be dumped in text format to file
61
<item>Analysing; the raw profile data is sorted and dumped
62
in text format either to file or console.</item>
64
<p>Since <c>fprof</c> uses trace to file, the runtime performance
65
degradation is minimized, but still far from negligible,
66
especially not for programs that use the filesystem heavily
67
by themselves. Where you place the trace file is also important,
68
e.g on Solaris <c>/tmp</c> is usually a good choice,
69
while any NFS mounted disk is a lousy choice.
71
<p>Fprof can also skip the file step and trace to a tracer process
72
of its own that does the profiling in runtime.
74
<p>The following sections show some examples of how to profile with
75
Fprof. See also the reference manual
76
<seealso marker="fprof">fprof(3)</seealso>.
80
<title>Profiling from the source code</title>
81
<p>If you can edit and recompile the source code, it is convenient
82
to insert <c>fprof:trace(start)</c> and
83
<c>fprof:trace(stop)</c> before and after the code to be
84
profiled. All spawned processes are also traced. If you want
85
some other filename than the default try
86
<c>fprof:trace(start, "my_fprof.trace")</c>.
88
<p>Then read the trace file and create the raw profile data with
89
<c>fprof:profile()</c>, or perhaps
90
<c>fprof:profile(file, "my_fprof.trace")</c> for non-default
93
<p>Finally create an informative table dumped on the console with
94
<c>fprof:analyse()</c>, or on file with
95
<c>fprof:analyse(dest, [])</c>, or perhaps even
96
<c>fprof:analyse([{dest, "my_fprof.analysis"}, {cols, 120}])</c>
97
for a wider listing on non-default filename.
99
<p>See the <seealso marker="fprof">fprof(3)</seealso> manual page
100
for more options and arguments to the functions
101
<seealso marker="fprof#trace">trace</seealso>,
102
<seealso marker="fprof#profile">profile</seealso>
104
<seealso marker="fprof#analyse">analyse</seealso>.
109
<title>Profiling a function</title>
110
<p>If you have one function that does the task that you want to
111
profile, and the function returns when the profiling should
112
stop, it is convenient to use
113
<c>fprof:apply(Module, Function, Args)</c> and related for the
116
<p>If the tracing should continue after the function returns, for
117
example if it is a start function that spawns processes to be
118
profiled, you can use
119
<c>fprof:apply(M, F, Args, [continue | OtherOpts])</c>.
120
The tracing has to be stopped at a suitable later time using
121
<c>fprof:trace(stop)</c>.
126
<title>Immediate profiling</title>
127
<p>It is also possible to trace immediately into the profiling
128
process that creates the raw profile data, that is to short
129
circuit the tracing and profiling steps so that the filesystem
132
<p>Do something like this:</p>
134
{ok, Tracer} = fprof:profile(start),
135
fprof:trace([start, {tracer, Tracer}]),
137
fprof:trace(stop);</pre>
138
<p>This puts less load on the filesystem, but much more on the
139
Erlang runtime system.