LuaProfiler can profile programs written in Lua 5.1.
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.
The easies way to install LuaProfiler is through LuaRocks.
luarocks install luaprofiler and LuaRocks will download and install
LuaProfiler on all major platforms.
If you want to install by hand, LuaProfiler source is distributed as a group of C files and some makefile templates.
LuaProfiler follows the
for Lua 5.1, therefore it should be "installed" in your
Windows users can use the pre-compiled version of LuaProfiler
profiler.dll) available at
require"profiler" in your script and this will define a
profiler module with two functions:
- Starts the profiler using the optional filename as the log file.
- Stops the profiler.
You can restart the profiler after a
stop with another call to
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
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.