LuaJIT platform profiler

Collecting a binary profile

To collect a binary profile for a particular part of the Lua and C code, you need to place this part between two misc.sysprof functions – namely, misc.sysprof.start() and misc.sysprof.stop() – and then execute the code in Tarantool.

Below is a chunk of Lua code named test.lua to illustrate this.

 1  local function payload()
 2    local function fib(n)
 3      if n <= 1 then
 4        return n
 5      end
 6      return fib(n - 1) + fib(n - 2)
 7    end
 8    return fib(32)
 9  end
10
11  payload()
12
13  local res, err = misc.sysprof.start({mode = 'C', interval = 1, path = 'sysprof.bin'})
14  assert(res, err)
15
16  payload()
17
18  res, err = misc.sysprof.stop()
19  assert(res, err)

The Lua code for starting the profiler – as in line 1 in the test.lua example above – is:

local str, err = misc.sysprof.start({mode = 'C', interval = 1, path = 'sysprof.bin'})

where:

• mode is a profiling mode;
• interval is a sampling interval;
• sysprof.bin is the name of the binary file where profiling events are written.

If the operation fails, for example if it is not possible to open a file for writing or if the profiler is already running, misc.sysprof.start() returns nil as the first result, an error-message string as the second result, and a system-dependent error code number as the third result.

If the operation succeeds, misc.sysprof.start() returns true.

The Lua code for stopping the profiler – as in line 15 in the test.lua example above – is:

local res, err = misc.sysprof.stop()

If the operation fails, for example if there is an error when the file descriptor is being closed or if there is a failure during reporting, misc.sysprof.stop() returns nil as the first result, an error-message string as the second result, and a system-dependent error code number as the third result.

If the operation succeeds, misc.sysprof.stop() returns true.

To generate a file with the memory profile in the binary format (in the test.lua code example above the file name is sysprof.bin), execute the code in Tarantool:

$ tarantool test.lua

Tarantool collects allocation events in sysprof.bin, puts the file in its working directory, and closes the session.

Parsing a binary profile and generating a profiling report

After getting the platform profile in the binary format, the next step is to parse it to get a human-readable profiling report. You can do this via Tarantool with the following command (mind the hyphen - before the filename):

$ tarantool -e 'require("sysprof")(arg)' - sysprof.bin > tmp
$ curl -O https://raw.githubusercontent.com/brendangregg/FlameGraph/refs/heads/master/flamegraph.pl
$ perl flamegraph.pl tmp > sysprof.svg

where sysprof.bin is the binary profile generated earlier by tarantool test.lua.

As for investigating the Lua code with the help of profiling reports, it is always code-dependent and there are no definite recommendations in this regard. Nevertheless, you can see some of the things in the Profiling report analysis example below.

Configuration C types

Profiler configuration settings include:

• typedef size_t (*sp_writer)(const void **data, size_t len, void *ctx) – a writer function for profile events.

  Must be async-safe, see also man 7 signal-safety.

  Should return the amount of written bytes on success, or zero in case of error.

  Setting *data to NULL means end of profiling. For details see lj_wbuf.h.

• typedef int (*sp_on_stop)(void *ctx, uint8_t *buf) – a callback on profiler stopping. Required for a correct cleanup at VM finalization when the profiler is still running.

  Returns zero on success.

• typedef void (*sp_backtracer)(void *(*frame_writer)(int frame_no, void *addr)) – a backtracing function for the host stack. Should call frame_writer on each frame in the stack, in the order from the stack top to the stack bottom.

  The frame_writer function is implemented inside sysprof and will be passed to the backtracer function.

  If frame_writer returns NULL, backtracing should be stopped. If frame_writer returns not NULL, the backtracing should be continued if there are frames left.

Profiler options

The options structure for luaM_sysprof_start is as follows:

struct luam_Sysprof_Options {
  /* Profiling mode. */
  uint8_t mode;

  /* Sampling interval in msec. */
  uint64_t interval;

  /* Custom buffer to write data. */
  uint8_t *buf;

  /* The buffer's size. */
  size_t len;

  /* Context for the profile writer and final callback. */
  void *ctx;
};

Profiling modes

The platform profiler supports three profiling modes:

• DEFAULT mode collects only data for luam_sysprof_counters, which is stored in memory and can be collected with luaM_sysprof_report after the profiler stops.
• LEAF mode = DEFAULT + streams samples with only top frames of the host and guests stacks in the format described in lj_sysprof.h.
• CALLGRAPH mode = DEFAULT + streams samples with full callchains of the host and guest stacks in the format described in lj_sysprof.h.

#define LUAM_SYSPROF_DEFAULT 0
#define LUAM_SYSPROF_LEAF 1
#define LUAM_SYSPROF_CALLGRAPH 2

Profiling counters

The counters structure for luaM_sysprof_report is as follows:

struct luam_Sysprof_Counters {
  uint64_t vmst_interp;
  uint64_t vmst_lfunc;
  uint64_t vmst_ffunc;
  uint64_t vmst_cfunc;
  uint64_t vmst_gc;
  uint64_t vmst_exit;
  uint64_t vmst_record;
  uint64_t vmst_opt;
  uint64_t vmst_asm;
  uint64_t vmst_trace;

  uint64_t samples;
};

Caveats

• Providing writers, backtracers and other settings in the Default mode is pointless, since it only collects counters.
• There is NO default configuration for sysprof, so luaM_Sysprof_Configure must be called before the first run of sysprof. Mind the async safety.