xray-instrument

Xray offers a function trace instrumentation which has very little overhead when trace capturing is disabled.

The xray system consists of compile time instrumentation, a runtime library to control capturing as well as tools for post processing.

During compilation functions are instrumented with nop space which is patched on the fly when tracing is enabled to hook function entry and exit points. Additional information for enabling the traces is placed in some special sections in the elf file.

The following provides an starting point example demonstrating

• account to gather function call statistics.
• convert to convert the binary trace into a trace format that can be opened by other tools (eg perfetto.dev or speedscope.app.

run: main
	XRAY_OPTIONS="patch_premain=true,xray_mode=xray-basic,verbosity=1" ./$< 1 2 3 4 5 > /dev/null
	llvm-xray account --instr_map=$< --sort=sum $$(ls -t1 xray-log.main.* | head -n1)
	llvm-xray convert --instr_map=$< --symbolize --output-format=trace_event $$(ls -t1 xray-log.main.* | head -n1)  | tee xray-trace.txt

main: main.c
	clang -o $@ $< -g -fxray-instrument -fxray-instruction-threshold=1

clean:
	$(RM) main xray-log.main.* xray-trace.txt

#include <unistd.h>

void work3() {
  usleep(3 * 1000);
}

void work2() {
  usleep(5 * 1000);
  work3();
}

void work1() {
  usleep(10 * 1000);
}

int main(int argc, char* argv[]) {
  for (int i = 0; i < argc; ++i) {
    work1();
    work2();
  }
}