english/tprof.tex
Version 1.2
Document 1.2
30/10/1996
The tcl profiler is a tool to create and analyse an execution profile of a tcl script. It may be used to identify performance bottlenecks or to get an overview of procedure interactions.
The main disadvantage of a scripting language like tcl is poor performance. As with other languages it is often enough to identify the spots where most of the cpu-cycles are spent and to rewrite (eg. in a compiled language like C) only the critical routines. This gives you the advantage of a fast development cycle by using an interactive language and the necessary speed improvements as soon as your application is ready for delivery.
Identifying performance bottlenecks of tcl requires two things:
To obtain performance data you need to instrument the code so that timing values for every procedure is recorded. It should also record the routine from which the current procedure is called and how often it was called.
The step of inspecting the raw data has to give the user an easy overview of the data obtained in the previous step and should allow interactive exploration of these data.
The main requirements of a tcl profiler should be
The Tcl-Profiler tries to implement the features mentioned above. It is seperated into two distinct parts - the data aquisition routine and the data display programm.
Getting performance data from a tcl script is done by using the profile command from the tclX package provided by Neosoft. See the next chapter for details about this command and for a description of the file format.
The phase of analysing the data files is completely decoupled from data aquisition. Tprof is a standalone programm to inspect performance data-sets created by the tprof procedure in the first step.
Tprof displays the data-set in three different formats:
this view is just a formatted listing of the data collected. It gives you absolute figures for all the timings and is primarily a cross-check for the other views.
the barchart display is used to identify the routines that require a lot of time.
this view displays the call hierarchy, that is the stack frames for all called procedures. It gives you an overview of the interconnections of your procedures.
Before running your application you have to instrument the tcl-script. With tprof this is easy:
source yourpath/SW/lib/tprof.tcl
This makes the command tprof available for later use. You have to replace yourpath with the actual value of the path where you installed the Tcl-Profiler.
tprof start
or alternatively
tprof start -commands
to start aquiring profiling data. The second form also collects data for Tcl's internal commands (the ones written in C).
tprof end filename
where filename is the name of a (non-existing) file where the profiling data-set will be stored.
Note that no data will be available if your programm terminates without calling tprof end first.
Thats all. Now execute your programm. When you finish it, a file with the name given in the tprof end command will be available for inspection.
If something goes wrong then the first thing to do is to check the file given in step 1. It tries to load the tclX package and may need another pathname to find it.
As mentioned above the Tcl-Profiler uses TclX to collect profiling data. Here is an excerpt from the TclX manual page:
This command is used to collect a performance profile of a Tcl script. It collects data at the Tcl procedure level. The number of calls to a procedure, and the amount of real and CPU time is collected. Time is also collected for the global context. The procedure data is collected by bucketing it based on the procedure call stack, this allows determination of how much time is spent in a particular procedure in each of it's calling contexts.
The on option enables profile data collection. If the -commands option is specified, data on all commands within a procedure is collected as well a procedures. Multiple occurrences of a command within a procedure are not distinguished, but this data may still be useful for analysis.
The off option turns off profiling and moves the data collected to the array arrayVar. The array is addressed by a list containing the procedure call stack. Element zero is the top of the stack, the procedure that the data is for. The data in each entry is a list consisting of the procedure call count and the real time and CPU time in milliseconds spent in the procedure (and all procedures it called). The list is in the form {count real cpu}.
Data-files written by the tprof command are plain text files and consist of three parts:
This header gives general information about the data-set (eg. time and date of creation, the version of tprof used and the command line of the instrumented programm). All header lines start with a # character.
The acutal profiling data is contained in the body of the file. Every record makes up one line. Any character before the first | in this line makes up a list containing the procedure call stack for the procedure at element zero. The remaining three arguments are the call count, the real and the cpu-time spent in this routine (and all procedures it called).
This is just a single line containing the text # eof.
The main part of the Tcl-Profiler is the data inspection tool. It is started with the following command line:
tprof filename
This works only if the Tcl-Profiler is installed correctly. Filename is an optional argument and gives the name of a data-set created by the profiling command described in the previous chapter.
The above screenshot of tprof gives you a general idea of the look and feel of the Tcl-Profiler. It displays one of the data-sets contained in the demo subdirectory of the distribution. Here it shows the graph of call interconnections and you can easily see which procedure calls which other procedures.
The menu at the top of the window contains entries to save and load data-sets, to export them in other formats, to print the data and to adjust display parameters.
The Data Set entry field may be used to load a new data-set (you may also use the menu File/Load Data Set) and always displays the filename of the currently loaded data-set.
The Context field displays the procedure name that is currently analyzed. It is empty if the complete data-set is displayed. If it contains a procedure name then only timing values for that procedure (and subprocedures) are listed in the chart and table displays.
As explained above the graph window displays the call stack of the programm. You can see that the procedure f1 called the procedures foreach, f2 and f3. Selecting a big data-set (eg data3.tprof form the demo directory) will give you an indication on how complicated such a call chain may be. To better visualize things you may play aroundwith the scale and offset of the image - select the Scaler utility from the menu Edit/Graph Scale and modify the values of the turndials.
The commercial version of tprof allows the selection of a specific procedure (eg f1 in the screenshot above) to switch to that context. Click on the button or enter the name of the procedure in the Context field. This results in an updated display where the given procedure is in the center and you can see which routines call your procedure and which routines are called by your procedure. This zoom-in facility is especially usefull for big datasets.
The barchart displays performance data of all (or a selected set if you zoomed in) procedures in your data-set. You may switch between the different types of data by clicking on the corresponding radio-buttons.
Noteable things for the barchart display of data are the low bound treshold that can be used to exclude procedures with minimal values (use the menu option Edit/Chart Treshold) to set the value (the example excludes all procedures that use less then 5 % of the cpu time of the procedure that uses the most time).
The procedure f0 has an upper and a lower bound for its timinig values (that is depending on how it is called it uses more or less time). The lowest bound is indicated by the break in the bar while the length of the bar corresponds to the high bound.
The red vertical line behind the bars is an indication of the average time used by all procedures.
Please notice the units when comparing different data sets - they are automatically adapted to show reasonable values so don't compare milliseconds with hours without thought.
This widget displays an ordered listing of the currently inspected data-set. It is intendended to inspect specific data values after you have found interesting procedures in either the graph- or the chart-widget.
As you can see from the screenshot a procedure may be listed more than once. You can also see that expr is called from six different locations and needs different times to complete according to the arguments given.
This widget displays information about the current data-sets. It is mainly for informational purposes, especially if you compare the current version of your programm with older versions. If you have merged data-sets with the menu option Edit/Merge Data Set then this window will list all the currently loaded data-sets.
Most of the menu entries are (hopefully) self-explanatory. Here is a description of some of the more exotic features:
The current data-set is saved under a possibly new name. If you merged multiple data sets with the menu option Edit/Merge Data Set then the new file will contain a union of all the data-sets.
This gives you the ability to export the data-set in a format that other programms can import. Most notably is the use of a spreadsheet for further data analysis. Currently supported formats include
The exported data may be directly used by sc and xspread. Some other programms contain import functions too.
this format is used by a lot of popular database packages.
this data may be read in by the Wingz spreadsheet programm (choose text format).
This is a plain formatted text output.
You may add additional data-sets to the current active data-set. This may be useful if you have data-sets from multiple invocations of your programm. This will give you more accurate results, especially for procedures that are called only once or twice.
This sends the data displayed in the currently active widget (Graph, Chart or Table) to a printer. It may be especially usefull for complicated graphs. The widget may also be saved into a file if you use Edit/Postscript (eps).
This enters the configuration editor. Check tprof for values you may want to modify. If you want to use Netscape instead of the internal browser to display help textes then set [About]:UseNetscape and [Help]:UseNetscape in the configuration file.
The programm tprof is available in two version:
This version is fully functional and contains essentially the same features as the commercial version. Missing is the zoom-in feature, merging and exporting of data-sets and most of the printing capabilities. The public-domain version is a lot slower as it uses more tcl-level routines (Sorry, but tprof provided the information for speeding itself...).
There is no guarany that the public-domain version will be available any longer, that it will be supported or that any bugs will be fixed.
This software may be used, copied, modified and distributed for free as long as the copyright stays intact and you don't make any money from it.
This version is fully functional and contains all the features described in the previous chapters. With the purchase of this software you are entitled to use the services of softWorks (maintenance, support, upgrades). Ask for more details about the commercial version of tprof (or just start the license-manager and select tprof).
This programm contains parts with their own copyrights like Tcl and its extensions TclX, Tk, Blt and Tix. These packages are all freely available from the internet.
IN NO EVENT SHALL THE AUTHOR OF THIS SOFTWARE BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR OF THIS SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHOR OF THIS SOFTWARE SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHOR OF THIS SOFTWARE HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
Additional information may be found in the document General Business Policy and Terms of Delivery.
As far as I know there is currently only one other package for profiling tcl scripts. This is also included in the TclX package and uses the command profrep to generate a text mode table of the results obtained by the profile command (the same command tprof uses).
This is the first version made available to the public. The subversion 1.1.1 is the public domain version, 1.1.2 is the commercial version.
This version contains no new functionality, only some bug fixes and improvements.
Currently there are no known bugs. There are probably some minor inconveniences hidden deep inside the program...