ltm

Linux的机器历史调试器。通过eBPF记录进程、文件、网络、内存和块I/O，将元数据存储在SQLite中，并回答关于设备上发生事件的时间线/差异/自然语言/SQL问题。

⚠️ 当前仅支持跟踪点捕获 — 目前记录使用跟踪点程序。尚未使用kprobes、uprobes、XDP或TC钩子，因此它偏向于稳定的系统调用/块/进程元数据，而不是更深入的内核内部、用户空间函数跟踪或数据包路径检查。

Quick start

go build -o bin/ltm ./cmd/ltm

sudo ./bin/ltm start                       # record (eBPF; root, Linux/x86_64)
./bin/ltm timeline --since 5m
./bin/ltm watch                            # live tail; Ctrl-C to stop
./bin/ltm diff --from 10m --to now
./bin/ltm query "who modified /etc/some.conf?"
sudo ./bin/ltm stop

记录需要root（或CAP_BPF + CAP_PERFMON）。查询不需要。如果没有活动的Linux记录器：ltm benchmark --count 1000 会向数据库注入合成事件，你可以使用timeline、diff和query进行查看。

全局标志放在子命令之前（ltm --db /tmp/ltm.db status）。默认值：DB ~/.local/share/ltm/ltm.db，PID ~/.local/run/ltm.pid。在任何读取命令中添加--json以获得机器可读的输出。

Commands

Storage and querying

一个SQLite数据库，由守护进程持有WAL写入器。每个读取路径以只读方式打开（PRAGMA query_only=ON）— 查询不会与写入器争用或修改日志。仅元数据；不包含文件内容。

export LTM_AGENT=claude   # or codex, cursor, gemini, auto, or a custom command
ltm query "which process wrote to files the most today?"

代理SQL会先打印，然后在只读连接上运行，除非是单独的SELECT，否则会被拒绝。没有代理（或代理失败）→ 使用内置模板。

What gets recorded

~60个跟踪点：进程（exec、exit、fork、clone、kill），文件（open/close、read/write、rename、unlink、link、symlink、mkdir、rmdir、chmod、chown、stat、access、truncate、dup、pipe，…），内存（mmap、munmap、mprotect），网络（socket、connect、bind、listen、accept、send/recv、shutdown），块（block_rq_issue）。

BPF会跳过/proc、/sys、/dev和守护进程自身的PID。手写的跟踪点清单位于internal/abi/abi.yaml；已检入的运行时刻表生成到internal/abi/tracepoints_gen.go。编辑collector.bpf.c后，使用make ebpf重建。编辑internal/abi/abi.yaml中的ABI元数据后，如果内核事件布局或跟踪点表发生更改，运行make generate，然后运行make ebpf。

Limitations

• 仅x86_64记录 — BPF使用-D__TARGET_ARCH_x86构建（#2）。查询和基准生成的演示数据不需要Linux记录支持。
• 仅支持IPv4地址 — IPv6的连接/绑定会以未解码地址存储。
• 字节计数是系统调用的请求大小（进入探针）；短/失败的I/O会多计；readv/writev/sendmsg/recvmsg报告0。
• fd→路径覆盖fd ≤ 1024，在PID严重重用后可能错误归属；更高的fd会记录为无路径。

Development

go test ./...                # local/unit tests
make generate                # regenerate ABI/schema outputs from abi.yaml
make ebpf                    # regenerate checked-in BPF object/bindings (Linux)
make integration             # real eBPF recording; Linux + root

布局：cmd/ltm入口点；其余都在internal/下（abi、cli、daemon、collector、ebpf、storage、agent、diff、query）。

ABI/模式生成器将事件定义、存储DDL、跟踪点元数据和面向内核的结构体绑定到一个单一事实来源：internal/abi/abi.yaml。其思想与CPython的Argument Clinic工作流（源）类似：当添加新的捕获事件/模块表面时，更新清单并重新生成检入的输出，而不是手动编辑派生的Go或C文件。

文档：docs/（ABI、CLI、生成的文件、查询、记录、架构、安全）。贡献者规则：AGENTS.md。