# FlexInstru

**Repository Path**: mwl2000/FlexInstru

## Basic Information

- **Project Name**: FlexInstru
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FlexInstru Profiler

---

## Overview
FlexInstru主要由如下几个部分组成：
- 自动配置脚本
- DynamoRIO的AArch64/X86客户端
这其中最为主要的程序为autoconfig.sh以及client中的相关代码

---

## Dependencies
- DynamoRIO version 10.0.19748
- CMake 3.7 or later

---

## Usage

### 0. Prerequisites

首先，需要确保`ptrace`系统调用被启用。

我们可以通过这样的命令来开启`ptrace`

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

### 1.Build
首先我们需要构建一个可用的client，FlexInstru同时支持AArch64和X86_64架构，需要根据具体的机器处理器架构来构建合适的client

如，在AArch64中，我们可以通过如下的命令构建所需的client
``` bash
cmake ..  -DCMAKE_INSTALL_PREFIX={Your install directory} -DTARGET_ARCH=AArch64 -DENABLE_PROJECTS={Clients you need}
```

ENABLE_PROJECTS可指定的值为branch,indirect和simd，你也可以同时指定多个client，如：
``` bash
cmake ..  -DCMAKE_INSTALL_PREFIX={Your install directory} -DTARGET_ARCH=AArch64 -DENABLE_PROJECTS="branch;indirect;simd"
```
这会同时构建三种client

### 2.Run


#### clients

FlexInstru的client的命令行参数，详见[这里](./docs/zh/client_zh.md)

#### Single/Multiple Profile

FlexInstru还提供了两个对mysql进行profiling的工具脚本：[single_profile.sh](./single_profile.sh)和[mulitiple_profile.sh](./multiple_profile.sh)。它们分别可以用来对mysql进行单次的profiling以及多次的profiling.

要使用这两个脚本对mysql进行profiling，我们需要了解几个常用参数的使用方法：

---
**dynamorio-home** <br/>
此参数指定dynamorio的安装路径，默认为`$HOME/dynamorio`

**mysql-server-base** <br/>
此参数指定mysql的安装路径，默认为`$HOME/mysql/mysql-server-8.0`

**sysbench-output-path** <br />
此参数指定sysbench的测量日志输出路径，默认为`$HOME/dynamorio/flexinstru/mysqld/sysbench_output.txt`

**instr-period** <br/>
指定每个测量时间段的长度，即论文中的$T_{interval}$。默认为100

**instr-sample** <br/>
指定每个测量时间段中采样的时间，即论文中的$T_{instrumentation}$，默认为10

**--time-period** <br/>
仅用于`multiple_profile.sh`中，设置一个attach-detach周期的长度，默认为20

**--time-sample** <br/>
仅用于`multiple_profile.sh`中，设置一个attach-detach周期中attach持续的时间，默认为8

---

#### Autoconfig

首先，我们可以通过自动配置脚本确定满足最大可容忍开销(MTO)的配置。关于自动配置脚本的更详细使用方法，详见[这里](./docs/zh/autoconfig_zh.md)。这里我们以AArch64下使用branchrecorder client，测量运行sysbench的mysql系统的性能（我们可以直接使用FlexInstru中给出的mysql_gauge.py）
``` bash
./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_only.lua --time=0 --mysql-port=13306
```

然后，根据运行的结果，我们再次运行client
``` bash
${DYNAMORIO_HOME}/bin64/drrun -root ${DYNAMORIO_HOME} -attach {mysql pid} -c {Path to branchrecorder} -p IR -s SR -o {Output filepath}
```

#### Bolt converter

FlexInstru还提供了一个用来将收集到的信息转换成bolt格式，并使用bolt对程序进行优化的工具`branch_data_transfer`，它位于安装目录的`utils`子目录中

这个工具的使用方法很简单，他接受两个命令行参数，-i表示输入的文件，-o表示输出的文件

---

## Gauge Specification

### What is the Gauge?
Gauge是用来为自动配置脚本选择合适的配置提供程序性能测量信息的工具

### How to write a Gauge?
所有的gauge都必须继承自基类autoconfig.gauge.gauge_base类，同时，在实现了自定义gauge类的模块中还必须提供一个`get_instance`函数

继承自gauge_base的类需要实现下面的这些纯虚函数：

``` python
def start_bench(self)
```
当自动配置脚本需要启动性能测量时，会调用该函数

``` python
def stop_bench(self)
```
当自动配置脚本需要停止性能测量时，会调用该函数

``` python
def get_throughput(self)
```
当自动配置脚本需要获取目标的吞吐量时，会调用该函数，我们约定返回的值为tps

``` python
def get_instance(args: str)
```
当自动配置脚本需要获取目标gauge实例时，会调用该函数，返回的值应该是当前gauge类的实例
args是自动配置脚本传递给gauge的参数

一个使用sysbench对mysql进行性能测量的gauge[例子](./autoconfig/gauge/mysql_gauge.py)

## Example
以上文提到的mysql gauge为例，我们使用`branchrecorder`对mysql进行性能测量。

### Configure-mysql

使用如下的配置来编译安装[mysql 8.0.26](https://github.com/mysql/mysql-server/tree/mysql-8.0.26)版本

首先，将mysql 8.0.26源码解压到本地，修改`CMakeLists.txt`文件，在该文件的580行处，添加
``` cmake
STRING_APPEND(CMAKE_C_FLAGS  " -fno-jump-tables")
STRING_APPEND(CMAKE_CXX_FLAGS " -fno-jump-tables")
STRING_APPEND(CMAKE_C_FLAGS " -no-pie")
STRING_APPEND(CMAKE_CXX_FLAGS " -no-pie")
```
以方便我们下一步使用dynamorio进行性能测量

此外，我们还要关闭`gold`链接器的使用，将`OPTION(USE_LD_GOLD "Use GNU gold linker" ON)`替换为`OPTION(USE_LD_GOLD "Use GNU gold linker" OFF)`

接下来，使用如下的命令编译：
``` bash
$ export CC=gcc 
$ export CXX=g++
$ mkdir build && cd build 
$ cmake .. -DWITH_BOOST={path of the boost_1_73_0 directory} -DCMAKE_CXX_LINK_FLAGS=-Wl,--emit-relocs -DCMAKE_C_LINK_FLAGS=-Wl,--emit-relocs -DBUILD_CONFIG=mysql_release 
$ make -j
$ make install
```

编译完成后，我们需要初始化mysql账户配置：
``` bash
$ chown -R {user} {path to MySQL directory}
$ {path to MySQL directory}/bin/mysqld --initialize-insecure --user=root --datadir={your data dir path of MySQL} 
$ {path to MySQL directory}/bin/mysqld --user=root --port=3306 --datadir={your data dir path of MySQL}
```

然后是测试使用的数据库配置：
``` bash
$ mysql -u root
$ CREATE USER 'flexinstru'@'localhost';
$ GRANT ALL PRIVILEGES ON *.* TO 'flexinstru'@'localhost' WITH GRANT OPTION;
$ CREATE DATABASE flexinstru_db;
$ QUIT;
$ mysqladmin -u root shutdown
```

### Configure-FlexInstru

首先，在FlexInstru的根目录下，执行：
``` bash
$ cmake -DCMAKE_INSTALL_PREFIX={Your Install Path} -DTARGET_ARCH={AArch64|x86_64} -DENABLE_PROJECTS="branch"
```

然后，执行`autoconfig`脚本以获取最佳配置
``` bash
$ autoconfig.sh --client {Your install path}/bin64/libbranchrecorder_bbl.so -m {Max tolerance you wanted} -p $(pgrep mysql | tail -n 1) -g autoconfig.gauge.mysql_gauge -- /usr/share/sysbench/oltp_read_only.lua
```

最后，`autoconfig`脚本会输出一段信息，提示你最佳配置的运行方法，你可以复制这个命令进行测量。
``` bash
......
Run command like:
drrun -c ${client} -p 100 -s {best_candidate[1]*100} -o Your_output_dir
At Instrumentation Ratio: {best_candidate[0]}
```

The function of process detachment has been integrated into the master repository of DynamoRIO in [#6513](https://github.com/DynamoRIO/dynamorio/pull/6513).