Usually Lua programs are profiled by setting hooks using the built-in function
debug.sethook, but sadly these hooks are not reliably called in luajit, which makes most profiling libraries for Lua not usable in the current version of löve.
jprof is a semi-makeshift solution for profiling löve applications with some extra work, but while also providing no significant slowdown while profiling.
jprof requires you to annotate your code with "profiling zones", which form a hierarchical representation of the overall flow of your program and record time taken and memory consumption for each of these zones:
function foo() prof.push("do the thing") thething() prof.pop() end function bar() prof.push("foo it up in here") foo() prof.pop("foo it up in here") prof.push("something else") local baz = sum(thing, else) prof.pop("something else") end
These are then saved to a file in your application's save directory using fperrad/lua-MessagePack, which you can analyze in the viewer:
Before you annotate your code, you need to copy (not move)
MessagePack.lua into your game's directory.
The most common case does probably look somewhat like this:
PROF_CAPTURE = true prof = require("jprof") function love.update(dt) prof.push("frame") -- push and pop additional zones here -- also update your game if you want end function love.draw() -- push and pop additional zones here prof.pop("frame") end function love.quit() prof.write("prof.mpack") end
PROF_CAPTURE evaluates to
false when jprof is imported, all profiling functions are replaced with
function() end i.e. do nothing, so you can leave them in even for release builds.
Also all other zones have to be pushed inside the
"frame" zone and whenever
prof.pop are called outside of a frame, the viewer will not know how to interpret that data (and error). So make sure capturing is disabled when functions are called that push zones outside of the
For example if you are using a fixed timestep loop (update and draw frames are not always 1 for 1), you probably want to do something like this instead (excerpt/sketch):
PROFILE_DRAW = false function love.update(dt) prof.enabled(not PROFILE_DRAW) prof.push("frame") -- updating prof.pop("frame") prof.enabled(false) end function love.draw() prof.enabled(PROFILE_DRAW) prof.push("frame") -- drawing prof.pop("frame") prof.enabled(false) end
annotation is optional and appears as metadata in the viewer.
name is optional and is only used to check if the current zone is actually the one specified as the argument. If not, somewhere before that pop-call another zone has been pushed, but not popped.
Pops all zones from the stack. You should almost never use this function, except if you want to terminate the program while having a number of zones on the zone stack (i.e. just before calling
prof.write()) and cleaning up properly would be too bothersome.
Writes the capture file to
Enables capturing profiling zones (
enabled = true) or disables it (
enabled = false). By default, profiling is enabled.
prof.connect(saveFullProfData, port, address)
Attempts to connect to the jprof viewer to transmit realtime profiling data. If
true, jprof will still save all the profiling data, so you can save it to file later using
prof.write(). If it is
false (default), the data is only transmitted to the viewer and
prof.write() will show a notice that no profiling data was saved.
1338 and the default
jprof does not send out every event by itself, but rather buffers them and sends them out, when this command is called. By default this is called when
prof.pop() is called and the popped zone is
"frame" (though only if you did
Just start the löve project contained in this repository like this:
love jprof <projectIdentity> <filename>
jprof also supports realtime transmission of profiling data. To use this feature, just start the viewer in listen mode:
love jprof listen
You may also pass an additional, optional argument to specify a port. The default port used is 1338. In the program you are profiling, call
prof.connect() (see above) right after importing jprof.
Note: When realtime profiling is used, it is not as straightforward to keep track of the memory jprof is using itself, since jprof will produce garbage too. Therefore the memory values returned by jprof will be less accurate and depending on your use case the garbage generated by jprof will dominate. Make sure to capture to file first and see if the live capture looks significantly different.
H to show the help overlay.
When you select a frame range, it will be averaged. Most of the time this is what you want to look at rather than individual frames.
If a single frame is selected the position of the zones in the flame graph will correspond to their relative position in time inside the frame, for averaged frames both in memory and time mode the zones will just be centered above their parent. Their size will still hold meaning though and empty space surrounding these zones implies that there was memory consumed/freed or time spent without being enclosed by a profiling zone.
The different modes (
time) determine whether the scale and position of the zones inside the flame graph will be derived from either memory consumption changes or time duration respectively.
The purple graph displays the total duration of the frames over time and the green graph the total memory consumption over time.
Graph Averaging Modes
maxmean is most useful for finding spikes. This is the default.
arithmeticmean is what most people think of, when they think of an average. This is less sensitive to spikes, but still somewhat.
harmonicmean is least sensitive to outliers and should be a bit smoother than the arithmetic mean.