tracepoint 框架
kernel/src/trace/ · 统一 trace-event 体系:单声明表派生事件全貌、tracefs 字节级对齐、两级门控与 per-CPU 环 —— 设计、全部事件清单与使用说明 · 观测性政策(2026-11-02):新增内核观测一律走本框架
§1设计:单声明表派生全部产物
每个事件在 tracepoints! 声明表中恰好出现一次 —— 一行声明该事件的全部面貌:组/名/id/逐字 print fmt/字段表/类型化调用签名/渲染器。由这一行声明,宏派生过去由手写站点重复携带的三样产物:
- 静态表行(group/name/id/print_fmt/fields/enabled)—— 表即目录;
- 记录函数
trace_<name>(field, ...) -> bool—— 类型化实参打包入参槽,armed 检查在函数内部(事件关闭时调用点只付实参求值); - 渲染器
<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 组)
| 组 | 数 | 事件 |
|---|---|---|
| rux | 20 | rux 自有族(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 |
| sched | 9 | sched_switch/sched_waking/sched_wakeup/sched_wakeup_new/sched_migrate_task/sched_process_fork/sched_process_exit/sched_process_free/sched_process_wait |
| ext4 | 7 | ext4_sync_file_enter/exit、ext4_ext_map_blocks_enter/exit、ext4_da_write_begin/end、ext4_free_blocks |
| net / binder / input | 5+5+4 | net: 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 |
| kmem | 4 | kmalloc/kfree/mm_page_alloc/mm_page_free |
| raw_syscalls / irq / exceptions / block / jbd2 | 2+2+2+2+2 | raw_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 | 各 1 | mm_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 全武装零 panic | 156 万次环覆写验证 |
门禁口径:trace 站点的存在不改变门禁带 —— armed 关闭态在反汇编层面即不可达路径;调度事件普查与 pbench 锚均在未武装配置上计测。
§4dfx= 遗留开关到事件的映射
旧散装开关表已冻结(见调试指南),其观测点迁移为 trace 事件,boot 参数 dfx=开关名 现为武装对应事件族的别名:
| dfx= 别名 | 武装的 rux: 事件 |
|---|---|
| dfx=taskdump | rux:taskdump(周期任务快照) |
| dfx=watchdog | 自旋锁告警 + rux:taskdump 联动 |
| dfx=memwatch | rux:memwatch(分配点记账) |
| dfx=mmforensics | rux:mmforensics(PTE 台账/双拆检测) |
| dfx=schedtrace | rux:schedtrace(调度步进) |
| dfx=sysring | rux:sysring(系统调用双录) |
| dfx=sigtrace | rux:sigtrace(信号链) |
| dfx=ohhunt | rux: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如何新增一个事件
- 在
kernel/src/trace/mod.rs的tracepoints!表加一行:组/名/id/print fmt(自 Linux 活文件逐字捕获,或对 rux: 族自拟)/字段表/call 签名/render。 - 调用点写
trace_<name>(实参...)—— 无需手写 armed 检查、打包或渲染。 - guest 侧验证:
cat events/<group>/<name>/format与 Linux format 逐字节比对(Linux 族),或与声明自洽(rux: 族)。 - 成本验证:release 反汇编确认调用点 one-load;开/关对照微基准给出启用代价。
政策依据:观测性政策(2026-11-02)—— 旧 dfx= 散装开关表冻结于 49 项不再增长;任何新观测点必须以 tracepoint 形态进入本框架。这是与 Linux 对齐的接口决策(debugfs/tracefs 生态直接可用),而非内部偏好。