README.md

LFSampler

LFSampler is a sample profiler, for Lua 5.1-5.4 or LuaJIT. It uses the jit profiler, if available, or the debug library. It can display the data in various formats.

Content

• Showcase
  • Interactive Flamegraphs
  • Source annotations
• Getting started
• Documentation
  • lfsampler
  • lfsampler.formatters
  • ProfilerResults
  • Other Structures
  • Anyting Missng?

Showcase

LFSampler can be used to generate several types of performance reports. Below you'll find a few examples you may run on some custom code:

Interactive Flamegraphs

How it works:

First dump collected stacktraces:

local lfsampler = require "lfsampler"
local formatter = require "lfsampler.formatter"

lfsampler.start()
-- Some code
lfsampler.stop()

local file = io.open("output.cap", "w")
file:write(formatter.flamegraph(lfsampler.popResults(), "graph", formatters.granularityFunc))
file:close()

Now use FlameGraph, to convert the dumped file into a interactive Flame Graph .svg:

<flamegraph> output.cap > output.svg

Flamegraphs are awesome, I highly recommend checking out this video.

Source annotations

How it works:

local lfsampler = require "lfsampler"
local formatter = require "lfsampler.formatter"

lfsampler.start()
-- Some code
lfsampler.stop()

local sources = formatter.annotateSource(lfsampler.popResults())
for name, data in pairs(sources) do
	local file = io.open(name:gsub("%.lua", ".tlua"):gsub("/", "."), "w")
	file:write(data)
	file:close()
end

Getting started

Installing

LFsampler is available via luarocks:

luarocks install lfsampler

An alternative way of installing is to clone or download and extract the source code of this project and add it to your package.path or drop the lfsampler folder into your package.path.

That's it! Once lfsampler is installed, it can be run on your code as shown below:

local lfsampler = require "lfsampler"
local formatter = require "lfsampler.formatter"

lfsampler.start()
-- Some code
lfsampler.stop()

local file = io.open("output.cap", "w")
file:write(formatter.formatReport(lfsampler.popResults()))
file:close()

would produce:

Documentation

Debugger priority at startup

1. JIT
2. debug
3. dummy

In code documentation available via Lua Language Server.

For detailed infos, see API Reference.

Anything missing?

"If you find any structure or function to be undocumented it was most likely intended for internal use inside the profiler. If you feel like something vital is missing, do not hesitate to open an issue.