aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/fprof_chapter.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/tools/doc/src/fprof_chapter.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/tools/doc/src/fprof_chapter.xml')
-rw-r--r--lib/tools/doc/src/fprof_chapter.xml141
1 files changed, 141 insertions, 0 deletions
diff --git a/lib/tools/doc/src/fprof_chapter.xml b/lib/tools/doc/src/fprof_chapter.xml
new file mode 100644
index 0000000000..3f40d93f40
--- /dev/null
+++ b/lib/tools/doc/src/fprof_chapter.xml
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2001</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>fprof - The File Trace Profiler</title>
+ <prepared>Raimo Niskanen</prepared>
+ <responsible>nobody</responsible>
+ <docno></docno>
+ <approved>nobody</approved>
+ <checked>no</checked>
+ <date>2001-08-14</date>
+ <rev>PA1</rev>
+ <file>fprof_chapter.xml</file>
+ </header>
+ <p><c>fprof</c> is a profiling tool that can be used to get a picture of
+ how much processing time different functions consumes and in which
+ processes.
+ </p>
+ <p><c>fprof</c> uses tracing with timestamps to collect profiling
+ data. Therfore there is no need for special compilation of any
+ module to be profiled.
+ </p>
+ <p><c>fprof</c> presents wall clock times from the host machine OS,
+ with the assumption that OS scheduling will randomly load the
+ profiled functions in a fair way. Both <em>own time</em> i.e the
+ time used by a function for its own execution, and
+ <em>accumulated time</em> i.e execution time including called
+ functions.
+ </p>
+ <p>Profiling is essentially done in 3 steps:</p>
+ <taglist>
+ <tag><c>1</c></tag>
+ <item>Tracing; to file, as mentioned in the previous paragraph.</item>
+ <tag><c>2</c></tag>
+ <item>Profiling; the trace file is read and raw profile data is
+ collected into an internal RAM storage on the node. During
+ this step the trace data may be dumped in text format to file
+ or console.</item>
+ <tag><c>3</c></tag>
+ <item>Analysing; the raw profile data is sorted and dumped
+ in text format either to file or console.</item>
+ </taglist>
+ <p>Since <c>fprof</c> uses trace to file, the runtime performance
+ degradation is minimized, but still far from negligible,
+ especially not for programs that use the filesystem heavily
+ by themselves. Where you place the trace file is also important,
+ e.g on Solaris <c>/tmp</c> is usually a good choice,
+ while any NFS mounted disk is a lousy choice.
+ </p>
+ <p>Fprof can also skip the file step and trace to a tracer process
+ of its own that does the profiling in runtime.
+ </p>
+ <p>The following sections show some examples of how to profile with
+ Fprof. See also the reference manual
+ <seealso marker="fprof">fprof(3)</seealso>.
+ </p>
+
+ <section>
+ <title>Profiling from the source code</title>
+ <p>If you can edit and recompile the source code, it is convenient
+ to insert <c>fprof:trace(start)</c> and
+ <c>fprof:trace(stop)</c> before and after the code to be
+ profiled. All spawned processes are also traced. If you want
+ some other filename than the default try
+ <c>fprof:trace(start, "my_fprof.trace")</c>.
+ </p>
+ <p>Then read the trace file and create the raw profile data with
+ <c>fprof:profile()</c>, or perhaps
+ <c>fprof:profile(file, "my_fprof.trace")</c> for non-default
+ filename.
+ </p>
+ <p>Finally create an informative table dumped on the console with
+ <c>fprof:analyse()</c>, or on file with
+ <c>fprof:analyse(dest, [])</c>, or perhaps even
+ <c>fprof:analyse([{dest, "my_fprof.analysis"}, {cols, 120}])</c>
+ for a wider listing on non-default filename.
+ </p>
+ <p>See the <seealso marker="fprof">fprof(3)</seealso> manual page
+ for more options and arguments to the functions
+ <seealso marker="fprof#trace">trace</seealso>,
+ <seealso marker="fprof#profile">profile</seealso>
+ and
+ <seealso marker="fprof#analyse">analyse</seealso>.
+ </p>
+ </section>
+
+ <section>
+ <title>Profiling a function</title>
+ <p>If you have one function that does the task that you want to
+ profile, and the function returns when the profiling should
+ stop, it is convenient to use
+ <c>fprof:apply(Module, Function, Args)</c> and related for the
+ tracing step.
+ </p>
+ <p>If the tracing should continue after the function returns, for
+ example if it is a start function that spawns processes to be
+ profiled, you can use
+ <c>fprof:apply(M, F, Args, [continue | OtherOpts])</c>.
+ The tracing has to be stopped at a suitable later time using
+ <c>fprof:trace(stop)</c>.
+ </p>
+ </section>
+
+ <section>
+ <title>Immediate profiling</title>
+ <p>It is also possible to trace immediately into the profiling
+ process that creates the raw profile data, that is to short
+ circuit the tracing and profiling steps so that the filesystem
+ is not used.
+ </p>
+ <p>Do something like this:</p>
+ <pre>
+{ok, Tracer} = fprof:profile(start),
+fprof:trace([start, {tracer, Tracer}]),
+%% Code to profile
+fprof:trace(stop);</pre>
+ <p>This puts less load on the filesystem, but much more on the
+ Erlang runtime system.
+ </p>
+ </section>
+</chapter>
+