1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE erlref SYSTEM "erlref.dtd"> 3 4<erlref> 5 <header> 6 <copyright> 7 <year>1996</year><year>2020</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>eprof</title> 26 <prepared></prepared> 27 <docno></docno> 28 <date></date> 29 <rev></rev> 30 </header> 31 <module since="">eprof</module> 32 <modulesummary>A Time Profiling Tool for Erlang</modulesummary> 33 <description> 34 <p>The module <c>eprof</c> provides a set of functions for time 35 profiling of Erlang programs to find out how the execution time is 36 used. The profiling is done using the Erlang trace BIFs. Tracing of 37 local function calls for a specified set of processes is enabled when 38 profiling is begun, and disabled when profiling is stopped.</p> 39 <p>When using Eprof, expect a slowdown in program execution.</p> 40 </description> 41 <funcs> 42 <func> 43 <name since="">start() -> {ok,Pid} | {error,Reason}</name> 44 <fsummary>Start Eprof.</fsummary> 45 <type> 46 <v>Pid = pid()</v> 47 <v>Reason = {already_started,Pid}</v> 48 </type> 49 <desc> 50 <p>Starts the Eprof server which holds the internal state of the collected data.</p> 51 </desc> 52 </func> 53 <func> 54 <name since="">start_profiling(Rootset) -> profiling | {error, Reason}</name> 55 <name since="OTP R14B">start_profiling(Rootset,Pattern) -> profiling | {error, Reason}</name> 56 <name since="OTP R16B01">start_profiling(Rootset,Pattern,Options) -> profiling | {error, Reason}</name> 57 <fsummary>Start profiling.</fsummary> 58 <type> 59 <v>Rootset = [atom() | pid()]</v> 60 <v>Pattern = {Module, Function, Arity}</v> 61 <v>Module = Function = atom()</v> 62 <v>Arity = integer()</v> 63 <v>Options = [set_on_spawn]</v> 64 <v>Reason = term()</v> 65 </type> 66 <desc> 67 <p>Starts profiling for the processes in <c>Rootset</c> (and any new 68 processes spawned from them). Information about activity in any 69 profiled process is stored in the Eprof database.</p> 70 <p><c>Rootset</c> is a list of pids and registered names.</p> 71 <p>The function returns <c>profiling</c> if tracing could be enabled 72 for all processes in <c>Rootset</c>, or <c>error</c> otherwise.</p> 73 <p>A pattern can be selected to narrow the profiling. For instance a 74 specific module can be selected, and only the code executed in that 75 module will be profiled.</p> 76 <p>The <c>set_on_spawn</c> option will active call time tracing for 77 all processes spawned by processes in the rootset. This is 78 the default behaviour.</p> 79 </desc> 80 </func> 81 <func> 82 <name since="">stop_profiling() -> profiling_stopped | profiling_already_stopped</name> 83 <fsummary>Stop profiling.</fsummary> 84 <desc> 85 <p>Stops profiling started with <c>start_profiling/1</c> or 86 <c>profile/1</c>.</p> 87 </desc> 88 </func> 89 <func> 90 <name since="">profile(Fun) -> profiling | {error, Reason}</name> 91 <name since="">profile(Fun, Options) -> profiling | {error, Reason}</name> 92 <name since="">profile(Rootset) -> profiling | {error, Reason}</name> 93 <name since="">profile(Rootset,Fun) -> {ok, Value} | {error,Reason}</name> 94 <name since="OTP R14B">profile(Rootset,Fun,Pattern) -> {ok, Value} | {error, Reason}</name> 95 <name since="">profile(Rootset,Module,Function,Args) -> {ok, Value} | {error, Reason}</name> 96 <name since="OTP R14B">profile(Rootset,Module,Function,Args,Pattern) -> {ok, Value} | {error, Reason}</name> 97 <name since="OTP R16B01">profile(Rootset,Module,Function,Args,Pattern,Options) -> {ok, Value} | {error, Reason}</name> 98 <fsummary>Start profiling.</fsummary> 99 <type> 100 <v>Rootset = [atom() | pid()]</v> 101 <v>Fun = fun() -> term() end</v> 102 <v>Pattern = {Module, Function, Arity}</v> 103 <v>Module = Function = atom()</v> 104 <v>Args = [term()]</v> 105 <v>Arity = integer()</v> 106 <v>Options = [set_on_spawn]</v> 107 <v>Value = Reason = term()</v> 108 </type> 109 <desc> 110 <p>This function first spawns a process <c>P</c> which evaluates 111 <c>Fun()</c> or <c>apply(Module,Function,Args)</c>. Then, it 112 starts profiling for <c>P</c> and the processes in <c>Rootset</c> 113 (and any new processes spawned from them). Information about 114 activity in any profiled process is stored in the Eprof database.</p> 115 <p><c>Rootset</c> is a list of pids and registered names.</p> 116 <p>If tracing could be enabled for <c>P</c> and all processes in 117 <c>Rootset</c>, the function returns <c>{ok,Value}</c> when 118 <c>Fun()</c>/<c>apply</c> returns with the value <c>Value</c>, or 119 <c>{error,Reason}</c> if <c>Fun()</c>/<c>apply</c> fails with 120 exit reason <c>Reason</c>. Otherwise it returns <c>{error, Reason}</c> 121 immediately.</p> 122 <p>The <c>set_on_spawn</c> option will active call time tracing for 123 all processes spawned by processes in the rootset. This is 124 the default behaviour.</p> 125 <p>The programmer must ensure that the function given as argument 126 is truly synchronous and that no work continues after 127 the function has returned a value.</p> 128 </desc> 129 </func> 130 <func> 131 <name since="OTP R14B">analyze() -> ok</name> 132 <name since="OTP R14B">analyze(Type) -> ok</name> 133 <name since="OTP R14B">analyze(Type,Options) -> ok</name> 134 <fsummary>Display profiling results per process.</fsummary> 135 <type> 136 <v>Type = procs | total</v> 137 <v>Options = [{filter, Filter} | {sort, Sort}</v> 138 <v>Filter = [{calls, integer()} | {time, float()}]</v> 139 <v>Sort = time | calls | mfa</v> 140 </type> 141 <desc> 142 <p>Call this function when profiling has been stopped to display 143 the results per process, that is:</p> 144 <list type="bulleted"> 145 <item>how much time has been used by each process, and</item> 146 <item>in which function calls this time has been spent.</item> 147 </list> 148 <p>Call <c>analyze</c> with <c>total</c> option when profiling has been stopped to display 149 the results per function call, that is in which function calls 150 the time has been spent.</p> 151 <p>Time is shown as percentage of total time and as absolute time.</p> 152 </desc> 153 </func> 154 <func> 155 <name since="">log(File) -> ok</name> 156 <fsummary>Activate logging of <c>eprof</c>printouts.</fsummary> 157 <type> 158 <v>File = atom() | string()</v> 159 </type> 160 <desc> 161 <p>This function ensures that the results displayed by 162 <c>analyze/0,1,2</c> are printed both to the file 163 <c>File</c> and the screen.</p> 164 </desc> 165 </func> 166 <func> 167 <name since="">stop() -> stopped</name> 168 <fsummary>Stop Eprof.</fsummary> 169 <desc> 170 <p>Stops the Eprof server.</p> 171 </desc> 172 </func> 173 </funcs> 174</erlref> 175 176