1 Introduction
2 Profiling
2.1 New Profile
2.2 Session Browser
2.3 Navigating a Session
2.4 Data Mining
3 Remote Profiling
1 Introduction
This is the reference manual for Tuna, the Perl profiler. It documents the latest version of Tuna.
There is a version of this manual suitable for printing available here.
2 Profiling
2.1 New Profile
To start a new profiling session, select New from the File menu. This window is also shown when first launching Tuna.

You can either use the Set button to locate the script, or enter its path directly. The contents of the Arguments field are passed to the program as arguments. If you need to pass special options directly to Perl, you should enter them after the #! in the script:
#!/usr/bin/perl -w
After pressing Launch, Tuna will run your script until it exits. If there are any problems, they will be presented in a sheet.
2.2 Session Browser

After running and analyzing the script, Tuna will present the session browser. This is a color coded call tree representing all the different function paths your program took, and how much time it spent in each.
Let's look at what information is available in this window. First, there are a few different columns in the table:
Self This indicates the amount of time spent in this function, not including subroutes it called. High values here indicate a function that does a lot of things on its own, or using Perl builtin functions. Total This is the total time for this function and all of its subroutines. Package Describes which code package the function belonged to. Packages are normally known as modules in the Perl world, but there are a few special packages. "main", for instance, is the default package under which functions placed directly in the script are listed. Sub The name of the function or subroutine.
There are also a few controls at the bottom of the window:
Stats Display Toggles between time, where the actual time values are shown, and percent, which display percent values of the total time. Color By Package Controls whether the call tree is colored by which package the function is included in. Hide Weight See 2.4.
2.3 Navigating a Session
In order to understand what the program was doing, we need to examine the call tree in more detail.

The program apparently spends half its time in various BEGIN routines, and the other half in a function called main. Let's say we're more interested in main, because we know most of the BEGIN calls are in modules not under our control.
Because the tree is ordered by total time spent, we can quickly drill down a bit from main and see which function took the most time on each level.

From this view, we see that displayComments calls itself a few times, and then calls another method display that uses the function process in the package Template. displayComments is a recursive function, which is why it appears multiple times like that. On each level, the time spent decreases a good chunk, so it looks like this function is pretty heavy.
2.4 Data Mining
To look closer on what displayComments is doing, we can use Tuna's Data Mining functions. Right-click on a function in the browser to pop up a context menu.

Here we select Focus Sub displayComments.

Now the view has been refocused as if displayComments was the root of the call tree. All percent values have been recalculated, and now indicate percent of time spent in displayComments. Data Mining Active has been lit up to indicate that the view has been modified.
To further clean up the view, we can enable the Hide Weight function.

Now Tuna will display only those functions that took 5% or more of the total time spent in displayComments.
The final data mining command available is Remove Callstack. Use it to remove from the view the entire call tree below the selected function, and recalculate all percent values, as if that call was never made.
To undo the last data mining operation and go back to the previous view, use the Restore command from the data mining menu. To undo all data mining operations and go back to the original view, use Restore All.
3 Remote Profiling
Tuna uses the Perl profiler Devel::DProf to generate its profiling data. You can also open a session generated directly from Devel::DProf in Tuna.
To profile a Perl script from the command line, use the -d flag:
$ perl -d:DProf /home/sites/animanga/scipts/comments.pl
Perl will run the script as it normally would, but also write a file called tmon.out to the current directory. This file can then be transferred to a computer with Tuna and opened either via the File menu's Open command, or just by double-clicking the file in Finder.