tracepoint 框架

kernel/src/trace/ · 统一 trace-event 体系:单声明表派生事件全貌、tracefs 字节级对齐、两级门控与 per-CPU 环 —— 设计、全部事件清单与使用说明 · 观测性政策(2026-11-02):新增内核观测一律走本框架

§1设计:单声明表派生全部产物

每个事件在 tracepoints! 声明表中恰好出现一次 —— 一行声明该事件的全部面貌:组/名/id/逐字 print fmt/字段表/类型化调用签名/渲染器。由这一行声明,宏派生过去由手写站点重复携带的三样产物:

  1. 静态表行(group/name/id/print_fmt/fields/enabled)—— 表即目录;
  2. 记录函数 trace_<name>(field, ...) -> bool —— 类型化实参打包入参槽,armed 检查在函数内部(事件关闭时调用点只付实参求值);
  3. 渲染器 <name>_fmt —— 文本输出与 format 文件共用。

设计要点:

  • print fmt 从 Linux 主机的活文件逐字捕获 —— 文本格式与字段偏移与 Linux 逐字节一致,任何宿主工具(解析 format 文件的事件分析器)无需修改即可工作。
  • 一个声明 = 一次编辑:表行、调用签名、文件形态是同一处修改 —— "格式与数据漂移"这类缺陷类在结构上不可表达(与 procfile! D-4 同一 derive 模式)。
  • 实参上限 10 个 u64 槽(TRACE_ARGS=10):一个 comm 占两槽;超界在编译期不可表达(PackArg trait 逐类型声明占用槽数)。
  • 两级门控:事件记录需事件自身 enable 与全局 tracing_on 同时开启;tracing_on 检查位于 record 内部、实参打包之后。

§2事件清单(69 事件 / 17 组)

组数事件
rux20rux 自有族(Linux 无对应事件):epoll_ctl_insert/epoll_ctl_remove/epoll_wait_scan/epoll_wait_exit/epoll_delivery、futex_miss、fuxstuck、hilog_census/hilog_kmsg/hilog_top、itimer_arm、memwatch、mmforensics、ohhunt、schedtrace、sigtrace、spinwatch/spinwatch_fd、sysring、taskdump、txnhang
sched9sched_switch/sched_waking/sched_wakeup/sched_wakeup_new/sched_migrate_task/sched_process_fork/sched_process_exit/sched_process_free/sched_process_wait
ext47ext4_sync_file_enter/exit、ext4_ext_map_blocks_enter/exit、ext4_da_write_begin/end、ext4_free_blocks
net / binder / input5+5+4net: udp_deliver/udp_wake/lo_xmit/sock_wait/pkt_drop;binder: binder_transaction/binder_transaction_received/binder_transaction_alloc_buf/binder_transaction_buffer_release/binder_wait_for_work;input: input_event/evdev_read/evdev_open/evdev_wake
kmem4kmalloc/kfree/mm_page_alloc/mm_page_free
raw_syscalls / irq / exceptions / block / jbd22+2+2+2+2raw_syscalls: sys_enter/sys_exit;irq: irq_handler_entry/exit;exceptions: page_fault_user/kernel;block: block_rq_issue/complete;jbd2: jbd2_start_commit/jbd2_end_commit
vmscan / timer / signal / printk / oom各 1mm_vmscan_lru_shrink_inactive、itimer_arm(计 rux)、signal_generate、printk:console、oom:mark_victim

rux: 族为登记的设计分歧形态:Linux 无 epoll/input 专属事件,属自有事件族 —— 语义上对齐其事件模型(组/名/id/format),内容为本内核特有观测点。

§3tracefs 文件树与使用

挂载后文件树与 Linux 逐文件对齐(标准名、标准 mode、字节格式自活主机 /sys/kernel/tracing 捕获):

mount -t tracefs none /sys/kernel/tracing
cd /sys/kernel/tracing
ls
# tracing_on  trace  trace_pipe  available_tracers  current_tracer
# available_events  set_event  buffer_size_kb  snapshot  options/
# events/<group>/{enable,filter,<event>/{enable,filter,id,format}}

cat events/sched/sched_wakeup/format     # 字段表 + print fmt(逐字节对齐 Linux)
cat events/sched/sched_wakeup/id         # 事件 id

典型会话

echo 1 > tracing_on                                # 全局总开关(两级门控的第二级)
echo 1 > events/sched/sched_switch/enable          # 武装单事件
echo 'sched:*' > set_event                          # 按组批量武装(支持通配与否定 !event)
echo 'ext4:* jbd2:*' > set_event                    # 多组
cat trace                                           # 读缓冲(读后不清;写 1 到 trace 清空)
cat trace_pipe                                      # 消费式读取,无表头
echo 4096 > buffer_size_kb                          # 每 CPU 环大小(KiB)
echo 1 > snapshot                                   # 存档当前环并重启活环;事后 cat snapshot
echo 0 > tracing_on                                 # 停止记录(武装保留)

输出行格式

%16s-%-7d [%03d] %c%c%c%c%c %5lu.%06lu: %s: %s
#      task      pid  cpu  irq 系列标志  时间戳        组:  内容
# 例:launcher-327  [002] d..1 1234.567890: sched:sched_switch: ...

环与一致性

  • per-CPU 环,逐 CPU 序列号,读侧时间戳合并 —— 尾延迟 p99 1.403→0.741 µs(−47%,观测自身的成本有测量)。
  • 600 s 全武装浸泡 156 万次环覆写零 panic —— 环满覆写路径经过验证。

§3b成本模型

状态成本验证方式
事件禁用单次 load + test + branch(调用点仅付实参求值)release 反汇编逐站点验证(全部 39 个内核站点 one-load:movzbl+test+jcc)
事件启用+13–19 ns/记录(纯写循环);+28–35 ns(epoll ping-pong 语境)开/关对照微基准
镜像代价+24,576 字节(+0.182%)构建体积对比
浸泡600 s 全武装零 panic156 万次环覆写验证

门禁口径:trace 站点的存在不改变门禁带 —— armed 关闭态在反汇编层面即不可达路径;调度事件普查与 pbench 锚均在未武装配置上计测。

§4dfx= 遗留开关到事件的映射

旧散装开关表已冻结(见调试指南),其观测点迁移为 trace 事件,boot 参数 dfx=开关名 现为武装对应事件族的别名:

dfx= 别名武装的 rux: 事件
dfx=taskdumprux:taskdump(周期任务快照)
dfx=watchdog自旋锁告警 + rux:taskdump 联动
dfx=memwatchrux:memwatch(分配点记账)
dfx=mmforensicsrux:mmforensics(PTE 台账/双拆检测)
dfx=schedtracerux:schedtrace(调度步进)
dfx=sysringrux:sysring(系统调用双录)
dfx=sigtracerux:sigtrace(信号链)
dfx=ohhuntrux:ohhunt(drm ioctl/mmap/prime-import)
dfx=fuxstuck / txnhang / spinwatch / hilogcensus对应 rux: 事件(专项狩猎观测点)

retired 令牌完整表与映射实现见 kernel/src/dfx/switches.rs(trace alias 表);/sys/kernel/debug/dfx/ 下有同一控制面的 debugfs 镜像。

§5如何新增一个事件

  1. 在 kernel/src/trace/mod.rs 的 tracepoints! 表加一行:组/名/id/print fmt(自 Linux 活文件逐字捕获,或对 rux: 族自拟)/字段表/call 签名/render。
  2. 调用点写 trace_<name>(实参...) —— 无需手写 armed 检查、打包或渲染。
  3. guest 侧验证:cat events/<group>/<name>/format 与 Linux format 逐字节比对(Linux 族),或与声明自洽(rux: 族)。
  4. 成本验证:release 反汇编确认调用点 one-load;开/关对照微基准给出启用代价。

政策依据:观测性政策(2026-11-02)—— 旧 dfx= 散装开关表冻结于 49 项不再增长;任何新观测点必须以 tracepoint 形态进入本框架。这是与 Linux 对齐的接口决策(debugfs/tracefs 生态直接可用),而非内部偏好。

代码:kernel/src/trace/mod.rs(宏 + 声明表)、kernel/src/trace/files.rs(tracefs 文件树)。相关:性能调试(syscost/pbench)、锁调试(lock: 观测)、调试指南(遗留开关表)。