FlexInstru

FlexInstru is a flexible instrumentation framework for tracing long-running native workloads through an attachment/detachment mechanism, making it convenient to collect the runtime characteristics of long-running applications in the production environment. By integrating process detachment with DynamoRIO’s existing process attachment capability, FlexInstru enables flexible control over instrumentation regions during execution. It further introduces an instrumentation sampling mechanism that adjusts the instrumentation ratio and sampling ratio to balance accuracy and overhead. An automated search plugin is also provided in FlexInstru to identify optimal ratio combinations under user-specified overhead constraints. This work has been published in Journal of Systems and Software.

---

Dependencies

• DynamoRIO version 10.0.19748
• CMake 3.7 or later

---

Usage

0. Prerequisites

First, we need to enable ptrace system call.

The following command can be used to enable ptrace:

$ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

1.Build

First we need to build an available client.FlexInstru supports both AArch64 and X86_64 architectures. We need to build the appropriate client according to the machine's processor architecture.

To build a client in AArch64, we can use the following command:

cmake ..  -DCMAKE_INSTALL_PREFIX={Your install directory} -DTARGET_ARCH=AArch64 -DENABLE_PROJECTS={Clients you need}

ENABLE_PROJECTS can be specified as branch, indirect and simd, and you can also specify multiple clients at the same build, such as:

cmake ..  -DCMAKE_INSTALL_PREFIX={Your install directory} -DTARGET_ARCH=AArch64 -DENABLE_PROJECTS="branch;indirect;simd"

All of them will be built.

2.Run

clients

Detailed command line options can be found in the README.md file in each client directory.

Single/Multiple Profile

FlexInstru provides two types of profiling scripts for MySQL : single_profile.sh and mulitiple_profile.sh.

To profiling MySQL using these two scripts, we can use these common options to get a quick start:

---

dynamorio-home
This parameter specifies the path where dynamorio is installed, default: $HOME/dynamorio

mysql-server-base
This parameter specifies the path where MySQL is installed, default: $HOME/mysql/mysql-server-8.0

sysbench-output-path
This parameter specifies where to save the output logs of sysbench, default: $HOME/dynamorio/flexinstru/mysqld/sysbench_output.txt

instr-period
This parameter specifies $T_{interval}$, default: 100

instr-sample
This parameter specifies $T_{instrumentation}$，default: 10

--time-period
Only multiple_profile.sh. This parameter specifies the length of an attach-detach duration, default: 20

--time-sample
Only multiple_profile.sh. This parameter specifies the length of sampling in each attach-detach duration, default: 4

---

Bolt converter

FlexInstru also provides a tool branch_data_transfer, located in the utils subdirectory of the installation directory, which is used to convert the collected information into bolt format and optimize the program using bolt.

This tool is easy-to-use, it takes two command line arguments, -i for the input file and -o for the output file.

---

Autoconfig

We can use the automatic configuration script to determine the optimal configuration that satisfies the Maximum Tolerable Overhead (MTO). For more details about the usage of the automatic configuration script, please refer to here. Here we use the branchrecorder client to measure the performance of the MySQL system running sysbench.

./autoconfig.sh --client ./clients/AArch64/bin64/libbranchrecorder_bbl.so -m 1.5 -p $(pgrep mysql) -g autoconfig.gauge.mysql_gauge -- /usr/share/sysbench/oltp_read_write.lua --time=0 --mysql-port=13306

Run client again with the optimal arguments obtained from the previous step.

${DYNAMORIO_HOME}/bin64/drrun -root ${DYNAMORIO_HOME} -attach {mysql pid} -c {Path to branchrecorder} -p IR -s SR -o {Output filepath}

The function of process detachment has been integrated into the master repository of DynamoRIO in #6513.