Introduction
More computing sins are committed in the name of efficiency (without necessarily achieving it) than for any other single reason - including blind stupidity. - W.A. WulfLuaProfiler can profile programs written in Lua 5.1, Lua 5.0, Lua 4.0, Lua 3.2 and LuaNG (used by older versions of CGILua).
There are several reasons to not optimize your program prematurely. Some of them include unnecessary loss of time, maintainability and robustness.
A profiler tells you what parts of your program are slow, so you can focus on them and forget about the rest. The slow parts are called bottlenecks. A bottleneck is a part of your program that is much slower than the rest of the program.
If you are programming in Lua, as a rule of thumb once you found a bottleneck you have two options: fine tune your code or, arguably the better option, redesigning your code.
To fine tune your Lua code, all you need to know is how slow the functions are. Then you can rewrite some of them, possibly in C. This option not necessarily improves significantly your performance.
To redesign your Lua code, you need more than that: you'll need to know how slow the functions are and which context makes them slow. A general solution aims to avoid unnecessary calls and loops.
When you do that, you reduce the complexity of your code, which can give you much more significant speed improvements in some situations. If you still need to speed things up and redesigning is not a viable option anymore, go ahead and fine tune the slower functions.
To fine tune, you need only timing numbers, but to redesign you need a better view of your program. This profiler helps you in these two processes.
For flexibility reasons, LuaProfiler is divided in 2 parts: the Lua code profiler, written in C to maximize the precision of timing, and the analyzer that generates information about the program execution, written in Lua to allow greater variance in the analysis process.
The code profiler produces as result a table of function calls and times that is usable by the analyzer itself or by a spreadsheet program, so you can analyze the results numerically to help you to fine tune your program.
Installation
LuaProfiler source is distributed as a group of C files and some makefile templates.
For older versions of Lua (3.2 and 4.0), LuaProfiler must be embedded in your application
(linked with it). You must call the function init_profiler() to start profiling from
C code.
LuaProfiler follows the
package model
for Lua 5.1, therefore it should be "installed" in your package.path.
Windows users can use the pre-compiled version of LuaProfiler
(profiler.dll) available at
LuaForge.
Using LuaProfiler
To profile your program for versions of Lua prior to 5.0, include luaProfiler.h
into your main module, include a call to init_profiler(L) after opening the Lua library
and recompile it using the appropriate LuaProfiler lib. If you are profiling Lua 3.2 programs,
consider L to be NULL.
For Lua 5.1 and 5.0, just require"profiler" in your script and this will define a
profiler module with two functions:
- start([filename])
- Starts the profiler using the optional filename as the log file.
- stop()
- Stops the profiler.
You can restart the profiler after a stop with another call to start.
All you need now is to run your program and get the output generated by the
profiler. The default log file is written to the working directory of the program,
in a file like lprof_randomid.out where randomid is
a random number. The log format uses a line for every function call in your program which may
result in huge files, so be careful with disk space if your program runs for a long time, or use
localized profiling wrapping the target section with a start()/stop()
call sequence.
LuaProfiler includes a script, summary.lua, that analyzes the output of the profiler
and generates a table with the functions used by your program and their running
times, ordered according to how much of the total execution time of your program the function
used. This script needs to be interpreted by Lua.
You can also pass the -v option to summary.lua, just before the name of the
log file, to generate a more comprehensive summary, containing the number of times each function
was called, their average running times, and the percentage of the total running time of your
script each function took.
Assuming the Lua interpreter is in your path, and both summary.lua and your output file are in the same directory, switch to the directory where the output file is and type:
lua summary.lua lprof_123456.out
For the verbose output, type:
lua summary.lua -v lprof_123456.out
You can also import the output file into a spreadsheet and analyze it there. Each line of the output file is a function call. The first line is a header that explains what each column contains. If you are using Excel for example, you can easily create a pivot table that shows the sum of times for the functions and then sort the cells so the bottlenecks are at the top.