Lua Academy · Lesson

Profiling with LuaProfiler

Instrument code with LuaProfiler to find CPU hotspots and call counts.

Profiling with LuaProfiler is a free Lua Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is LuaProfiler?

LuaProfiler is a hook-based profiler for Lua. It records function call counts and cumulative time spent in each function, producing a report for optimization analysis.

Installing LuaProfiler

Available via LuaRocks: luarocks install luaprofiler. Or include the source directly in your project.

Starting the Profiler

Wrap your code with profiler start/stop calls.

local profiler = require("profiler")
profiler.start("profile.txt")  -- output to file
-- ... your code ...
profiler.stop()

Reading the Report

The report shows: function name, call count, time per call, total time. Focus on functions with high total time.

-- Example report:
-- function          calls  total_time  avg_time
-- hotLoop          1000   0.850 s     0.850 ms
-- table.sort        200   0.120 s     0.600 ms
-- string.format    5000   0.090 s     0.018 ms

Profiling Specific Code Paths

Profile only a subset of your code to reduce overhead and focus the report.

profiler.start()
doExpensiveOperation()
profiler.stop()
profiler.report("expensive_op.txt")

Alternative: Custom Profiler with debug.sethook

Build a minimal profiler using debug.sethook to collect call counts without an external library.

local counts = {}
debug.sethook(function(event)
  if event == "call" then
    local info = debug.getinfo(2, "n")
    local name = info.name or "?"
    counts[name] = (counts[name] or 0) + 1
  end
end, "c")
-- ... run code ...
debug.sethook()
for name, count in pairs(counts) do
  print(count, name)
end

os.clock for Function Timing

Time individual functions manually for quick targeted benchmarks.

local function time(fn, ...)
  local t = os.clock()
  fn(...)
  return os.clock() - t
end
print("myFunc took:", time(myFunc, arg1, arg2))

jit.p for LuaJIT Profiling

On LuaJIT, jit.p is superior to hook-based profilers for production use: lower overhead and JIT-aware sampling.

Flame Graphs

Generate a flame graph by collecting stack samples. Tools: lua-flameprof for PUC Lua, jit.p + FlameGraph for LuaJIT. Flame graphs show the entire call hierarchy of CPU usage.

Profiling in Test Suites

Run the profiler inside unit tests to catch performance regressions automatically. Assert that hotspot functions don't exceed a time threshold.

Common Hotspots

String concatenation with .. in loops (use table.concat).
table.sort on large tables (consider a faster algorithm).
Frequent closure creation.
Deep metatable __index chains.

Profiling Question

What does a LuaProfiler report show?

Recap: Profiling with LuaProfiler

Use LuaProfiler or a custom debug.sethook profiler to collect call counts and timings. Focus on functions with high total time. On LuaJIT, prefer jit.p. Use flame graphs for call-hierarchy visualization.

Frequently asked questions

Is the “Profiling with LuaProfiler” lesson free?

Yes — the full text of “Profiling with LuaProfiler” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.

What will I learn in “Profiling with LuaProfiler”?

Instrument code with LuaProfiler to find CPU hotspots and call counts. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Lua Academy?

No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Profiling with LuaProfiler” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Lua Academy lesson?

Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Lua Academy