+LuaJIT has an integrated statistical profiler with very low overhead. It +allows sampling the currently executing stack and other parameters in +regular intervals. +
++The integrated profiler can be accessed from three levels: +
+-
+
- The bundled high-level profiler, invoked by the +-jp command line option. +
- A low-level Lua API to control the profiler. +
- A low-level C API to control the profiler. +
High-Level Profiler
++The bundled high-level profiler offers basic profiling functionality. It +generates simple textual summaries or source code annotations. It can be +accessed with the -jp command line option +or from Lua code by loading the underlying jit.p module. +
++To cut to the chase — run this to get a CPU usage profile by +function name: +
++luajit -jp myapp.lua ++
+It's not a stated goal of the bundled profiler to add every +possible option or to cater for special profiling needs. The low-level +profiler APIs are documented below. They may be used by third-party +authors to implement advanced functionality, e.g. IDE integration or +graphical profilers. +
++Note: Sampling works for both interpreted and JIT-compiled code. The +results for JIT-compiled code may sometimes be surprising. LuaJIT +heavily optimizes and inlines Lua code — there's no simple +one-to-one correspondence between source code lines and the sampled +machine code. +
+ +-jp=[options[,output]]
++The -jp command line option starts the high-level profiler. +When the application run by the command line terminates, the profiler +stops and writes the results to stdout or to the specified +output file. +
++The options argument specifies how the profiling is to be +performed: +
+-
+
- f — Stack dump: function name, otherwise module:line. +This is the default mode. +
- F — Stack dump: ditto, but dump module:name. +
- l — Stack dump: module:line. +
- <number> — stack dump depth (callee ← +caller). Default: 1. +
- -<number> — Inverse stack dump depth (caller +→ callee). +
- s — Split stack dump after first stack level. Implies +depth ≥ 2 or depth ≤ -2. +
- p — Show full path for module names. +
- v — Show VM states. +
- z — Show zones. +
- r — Show raw sample counts. Default: show percentages. +
- a — Annotate excerpts from source code files. +
- A — Annotate complete source code files. +
- G — Produce raw output suitable for graphical tools. +
- m<number> — Minimum sample percentage to be shown. +Default: 3%. +
- i<number> — Sampling interval in milliseconds.
+Default: 10ms.
+Note: The actual sampling precision is OS-dependent.
+
+The default output for -jp is a list of the most CPU consuming +spots in the application. Increasing the stack dump depth with (say) +-jp=2 may help to point out the main callers or callees of +hotspots. But sample aggregation is still flat per unique stack dump. +
++To get a two-level view (split view) of callers/callees, use +-jp=s or -jp=-s. The percentages shown for the second +level are relative to the first level. +
++To see how much time is spent in each line relative to a function, use +-jp=fl. +
++To see how much time is spent in different VM states or +zones, use -jp=v or -jp=z. +
++Combinations of v/z with f/F/l produce two-level +views, e.g. -jp=vf or -jp=fv. This shows the time +spent in a VM state or zone vs. hotspots. This can be used to answer +questions like "Which time consuming functions are only interpreted?" or +"What's the garbage collector overhead for a specific function?". +
++Multiple options can be combined — but not all combinations make +sense, see above. E.g. -jp=3si4m1 samples three stack levels +deep in 4ms intervals and shows a split view of the CPU consuming +functions and their callers with a 1% threshold. +
++Source code annotations produced by -jp=a or -jp=A are +always flat and at the line level. Obviously, the source code files need +to be readable by the profiler script. +
++The high-level profiler can also be started and stopped from Lua code with: +
+
+require("jit.p").start(options, output)
+...
+require("jit.p").stop()
+
+
+jit.zone — Zones
++Zones can be used to provide information about different parts of an +application to the high-level profiler. E.g. a game could make use of an +"AI" zone, a "PHYS" zone, etc. Zones are hierarchical, +organized as a stack. +
++The jit.zone module needs to be loaded explicitly: +
+
+local zone = require("jit.zone")
+
+-
+
- zone("name") pushes a named zone to the zone stack. +
- zone() pops the current zone from the zone stack and +returns its name. +
- zone:get() returns the current zone name or nil. +
- zone:flush() flushes the zone stack. +
+To show the time spent in each zone use -jp=z. To show the time +spent relative to hotspots use e.g. -jp=zf or -jp=fz. +
+ +Low-level Lua API
++The jit.profile module gives access to the low-level API of the +profiler from Lua code. This module needs to be loaded explicitly: +
+local profile = require("jit.profile")
+
++This module can be used to implement your own higher-level profiler. +A typical profiling run starts the profiler, captures stack dumps in +the profiler callback, adds them to a hash table to aggregate the number +of samples, stops the profiler and then analyzes all of the captured +stack dumps. Other parameters can be sampled in the profiler callback, +too. But it's important not to spend too much time in the callback, +since this may skew the statistics. +
+ +profile.start(mode, cb) +— Start profiler
++This function starts the profiler. The mode argument is a +string holding options: +
+-
+
- f — Profile with precision down to the function level. +
- l — Profile with precision down to the line level. +
- i<number> — Sampling interval in milliseconds (default +10ms). +Note: The actual sampling precision is OS-dependent. + +
+The cb argument is a callback function which is called with +three arguments: (thread, samples, vmstate). The callback is +called on a separate coroutine, the thread argument is the +state that holds the stack to sample for profiling. Note: do +not modify the stack of that state or call functions on it. +
++samples gives the number of accumulated samples since the last +callback (usually 1). +
++vmstate holds the VM state at the time the profiling timer +triggered. This may or may not correspond to the state of the VM when +the profiling callback is called. The state is either 'N' +native (compiled) code, 'I' interpreted code, 'C' +C code, 'G' the garbage collector, or 'J' the JIT +compiler. +
+ +profile.stop() +— Stop profiler
++This function stops the profiler. +
+ +dump = profile.dumpstack([thread,] fmt, depth) +— Dump stack
++This function allows taking stack dumps in an efficient manner. It +returns a string with a stack dump for the thread (coroutine), +formatted according to the fmt argument: +
+-
+
- p — Preserve the full path for module names. Otherwise +only the file name is used. +
- f — Dump the function name if it can be derived. Otherwise +use module:line. +
- F — Ditto, but dump module:name. +
- l — Dump module:line. +
- Z — Zap the following characters for the last dumped +frame. +
- All other characters are added verbatim to the output string. +
+The depth argument gives the number of frames to dump, starting +at the topmost frame of the thread. A negative number dumps the frames in +inverse order. +
++The first example prints a list of the current module names and line +numbers of up to 10 frames in separate lines. The second example prints +semicolon-separated function names for all frames (up to 100) in inverse +order: +
++print(profile.dumpstack(thread, "l\n", 10)) +print(profile.dumpstack(thread, "lZ;", -100)) ++ +
Low-level C API
++The profiler can be controlled directly from C code, e.g. for +use by IDEs. The declarations are in "luajit.h" (see +Lua/C API extensions). +
+ +luaJIT_profile_start(L, mode, cb, data) +— Start profiler
++This function starts the profiler. See +above for a description of the mode argument. +
++The cb argument is a callback function with the following +declaration: +
++typedef void (*luaJIT_profile_callback)(void *data, lua_State *L, + int samples, int vmstate); ++
+data is available for use by the callback. L is the +state that holds the stack to sample for profiling. Note: do +not modify this stack or call functions on this stack — +use a separate coroutine for this purpose. See +above for a description of samples and vmstate. +
+ +luaJIT_profile_stop(L) +— Stop profiler
++This function stops the profiler. +
+ +p = luaJIT_profile_dumpstack(L, fmt, depth, len) +— Dump stack
++This function allows taking stack dumps in an efficient manner. +See above for a description of fmt +and depth. +
++This function returns a const char * pointing to a +private string buffer of the profiler. The int *len +argument returns the length of the output string. The buffer is +overwritten on the next call and deallocated when the profiler stops. +You either need to consume the content immediately or copy it for later +use. +
++