← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/tools/doc/src/fprof_chapter.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/tools/doc/src/fprof_chapter.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2001</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
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/.
 
17
 
 
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
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>fprof - The File Trace Profiler</title>
 
27
    <prepared>Raimo Niskanen</prepared>
 
28
    <responsible>nobody</responsible>
 
29
    <docno></docno>
 
30
    <approved>nobody</approved>
 
31
    <checked>no</checked>
 
32
    <date>2001-08-14</date>
 
33
    <rev>PA1</rev>
 
34
    <file>fprof_chapter.sgml</file>
 
35
  </header>
 
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
 
38
    processes.
 
39
    </p>
 
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.
 
43
    </p>
 
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
 
49
    functions. 
 
50
    </p>
 
51
  <p>Profiling is essentially done in 3 steps:</p>
 
52
  <taglist>
 
53
    <tag><c>1</c></tag>
 
54
    <item>Tracing; to file, as mentioned in the previous paragraph.</item>
 
55
    <tag><c>2</c></tag>
 
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
 
59
     or console.</item>
 
60
    <tag><c>3</c></tag>
 
61
    <item>Analysing; the raw profile data is sorted and dumped
 
62
     in text format either to file or console.</item>
 
63
  </taglist>
 
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.
 
70
    </p>
 
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.
 
73
    </p>
 
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>.
 
77
    </p>
 
78
 
 
79
  <section>
 
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>.
 
87
      </p>
 
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
 
91
      filename. 
 
92
      </p>
 
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.
 
98
      </p>
 
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>
 
103
      and 
 
104
      <seealso marker="fprof#analyse">analyse</seealso>.
 
105
      </p>
 
106
  </section>
 
107
 
 
108
  <section>
 
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
 
114
      tracing step.
 
115
      </p>
 
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>.
 
122
      </p>
 
123
  </section>
 
124
 
 
125
  <section>
 
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
 
130
      is not used.
 
131
      </p>
 
132
    <p>Do something like this:</p>
 
133
    <pre>
 
134
{ok, Tracer} = fprof:profile(start),
 
135
fprof:trace([start, {tracer, Tracer}]),
 
136
%% Code to profile
 
137
fprof:trace(stop);</pre>
 
138
    <p>This puts less load on the filesystem, but much more on the
 
139
      Erlang runtime system.
 
140
      </p>
 
141
  </section>
 
142
</chapter>
 
143