Top AI Repos — open-source AI, indexed and scored
Top AI Repos tracks AI repositories on GitHub and answers two different questions about each one: is it moving right now, and would you bet a product on it.
Top AI Repos tracks AI repositories on GitHub and answers two different questions about each one: is it moving right now, and would you bet a product on it.
surftrace is a tool that allows you to surf the linux kernel
| Date | Stars |
|---|---|
| 2026-07-24 | 328 |
| 2026-07-25 | 328 |
| 2026-07-28 | 328 |
| 2026-07-30 | 328 |
| 2026-08-06 | 328 |
Today
— stars today
This week
— stars this week
This month
— stars this month
Momentum
0.0
growth rate 0.00%/day
# 1、简介
 surftrace是一个ftrace的自动封装器和开发编译平台，既能让用户基于libbpf快速构建工程进行开发，也能作为ftrace的封装器进行trace命令编写。项目包含surftrace工具集和pylcc、glcc(python or generic C language for libbpf Compiler Collection)，提供远程和本地eBPF的编译能力。
## 1.1、ftrace原理与不足
 ftrace是一个内核中的追踪器，用于帮助系统开发者或设计者查看内核运行情况，它可以被用来调试或者分析延迟/性能等常见问题。早期 ftrace 是一个 function tracer，仅能够记录内核的函数调用流程。如今ftrace已经成为一个开发框架，从2.6内核开始引入，是一套公认安全、可靠、高效的内核数据获取方式。
 ftrace对使用者的要求比较高，以对内核符号 wake\_up\_new\_task 进行trace，同时要获取入参(struct task\_struct *)->comm 成员信息为例，启动配置需要经历三个步骤：
```bash
echo 'p:f0 wake_up_new_task comm=+0x678(%di):string' >> /sys/kernel/debug/tracing/kprobe_events
echo 1 > /sys/kernel/debug/tracing/instances/surftrace/events/kprobes/f0/enable
echo 1 > /sys/kernel/debug/tracing/instances/surftrace/tracing_on
```
 要想停止需要继续配置如下：
```bash
echo 0 > /sys/kernel/debug/tracing/instances/surftrace/events/kprobes/f0/enable
echo -:f0 >> /sys/kernel/debug/tracing/kprobe_events
echo 0 > /sys/kernel/debug/tracing/instances/surftrace/tracing_on
```
 一共需要六个步骤。其中，最困难的是第一个参数解析步骤。通常情况下，需要使用gdb 加载对应内核vmlinux， 对 struct task_struct 结构体中 comm成员进行偏移计算。上述方法如果不经常使用，重新手工操作的时间成本非常高，导致真正直接采用ftrace对内核信息进行采集的案例非常少，相关资料文献也匮乏。
## 1.2、surftrace目标
 surftrace的主要目标是为了降低内核trace难度，达到快速高效获取内核信息目标。综合来说要达到以下效果：
- 1. 一键trace内核符号，并获取指定内核数据；
- 2. 除了C和linux 操作系统内核，用户无需新增学习掌握其它知识点（需要获取数据进行二次处理除外）；
- 3. 覆盖大部分主流发行版内核；
- 4. 类似bcc开发模式，达到libbpf最佳资源消耗；
# 2、surftrace 命令使用
 使用surftrace，需要满足以下条件：
- 1. 公开发行版linux内核，支持目录清单参考：http://mirrors.openanolis.cn/coolbpf/db/ （持续更新）
- 2. 内核支持ftrace，已配置了debugfs，root权限；
- 3. Python2 >= 2.7; Python3 >= 3.5，已安装pip；
surftrace支持 remote（默认），local和gdb三种表达式解析器，要求分别如下：
- 1. remote mode：可以访问pylcc.openanolis.cn
- 2. local mode：从http://pylcc.openanolis.cn/db/ 下载对应arch和内核的下载到本地
- 3. gdb mode：gdb version > 8.0，存放有对应内核的vmlinux；对于gdb模式而言，不受公开发行版内核限制(性能太弱，已经不再推荐)
## 2.1、安装
 我们以龙蜥 4.19.91-24.8.an8.x86_64内核为例，需要root用户，执行以下命令进行安装：
```
pip3 install surftrace
Collecting surftrace
Downloading http://mirrors.cloud.aliyuncs.com/pypi/packages/b9/a2/f7e04bb8ebb12e6517162a70886e3ffe8d466437b15624590c9301fdcc52/surftrace-0.2.tar.gz
Building wheels for collected packages: surftrace
Running setup.py bdist_wheel for surftrace ... done
Stored in directory: /root/.cache/pip/wheels/cf/28/93/187f359be189bf0bf4a70197c53519c6ca54ffb957bcbebf5a
Successfully built surftrace
Installing collected packages: surftrace
Successfully installed surftrace-0.2
```
 0.6以上（含）的版本采用https流的方式与服务器传输数据，低于0.6版本采用tcp 流传输。后者服务将从2023年12月31号起后下线。
 检查安装是否成功
```
surftrace --help
usage: surftrace [-h] [-v VMLINUX] [-m MODE] [-d DB] [-r RIP] [-f FILE]
[-g GDB] [-F FUNC] [-o OUTPUT] [-l LINE] [-a ARCH] [-s] [-S]
[traces [traces ...]]
Trace ftrace kprobe events.
positional arguments:
traces set trace args.
optional arguments:
-h, --help show this help message and exit
-v VMLINUX, --vmlinux VMLINUX
set vmlinux path.
-m MODE, --mode MODE set arg parser, fro
-d DB, --db DB set local db path.
-r RIP, --rip RIP set remote server ip, remote mode only.
-f FILE, --file FILE set input args path.
-g GDB, --gdb GDB set gdb exe file path.
-F FUNC, --func FUNC disasassemble function.
-o OUTPUT, --output OUTPUT
set output bash file
-l LINE, --line LINE get file disasemble info
-a ARCH, --arch ARCH set architecture.
-s, --stack show call stacks.
-S, --show only show expressions.
examples:
```
## 2.2、常规函数入口trace
 接下来我们以 以下两个常用内核符号为例，它的原型定义如下：
```c
void wake_up_new_task(struct task_struct *p);
struct file *do_filp_open(int dfd, struct filename *pathname, const struct open_flags *op);
```
### 2.2.1、追踪符号入口和返回点
- 命令：surftrace 'p wake_up_new_task' 'r wake_up_new_task'
```bash
surftrace 'p wake_up_new_task' 'r wake_up_new_task'
echo 'p:f0 wake_up_neExcerpt of 59,193 characters
Read on GitHubWould you bet a product on this? Bounded 0–100 and slow moving.
matched fp:d057324cd772d111, topic:tracing