ltm

Debugger della cronologia macchina per Linux. Registra processi, file, rete, memoria e I/O a blocchi tramite eBPF, memorizza i metadati in SQLite e risponde a domande su cronologia / differenze / linguaggio naturale / SQL su ciò che è accaduto sul sistema.

⚠️ Cattura solo tramite tracepoint oggi — la registrazione attualmente utilizza programmi tracepoint. Non utilizza ancora kprobe, uprobe, XDP o hook TC, quindi predilige metadati stabili di syscall/block/process piuttosto che interni del kernel più profondi, tracciamento di funzioni in spazio utente o ispezione del percorso dei pacchetti.

Avvio rapido

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

La registrazione necessita di root (o CAP_BPF + CAP_PERFMON). Le interrogazioni no. Senza un registratore Linux attivo: ltm benchmark --count 1000 inserisce eventi sintetici in un DB che puoi ispezionare con timeline, diff e query.

I flag globali vanno prima del sottocomando (ltm --db /tmp/ltm.db status). Predefiniti: DB ~/.local/share/ltm/ltm.db, PID ~/.local/run/ltm.pid. Aggiungi --json a qualsiasi comando di lettura per output leggibile dalla macchina.

Comandi

Archiviazione e interrogazione

Un database SQLite, writer WAL trattenuto dal demone. Ogni percorso di lettura apre in sola lettura (PRAGMA query_only=ON) — le interrogazioni non competono mai con lo scrittore né mutano il log. Solo metadati; nessun contenuto di file.

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

L'SQL dell'agente viene stampato, poi eseguito sulla connessione in sola lettura e rifiutato a meno che non sia un singolo SELECT. Nessun agente (o fallimento dell'agente) → modelli incorporati.

Cosa viene registrato

~60 tracepoint: processo (exec, exit, fork, clone, kill), file (open/close, read/write, rename, unlink, link, symlink, mkdir, rmdir, chmod, chown, stat, access, truncate, dup, pipe, …), memoria (mmap, munmap, mprotect), rete (socket, connect, bind, listen, accept, send/recv, shutdown), blocco (block_rq_issue).

BPF salta /proc, /sys, /dev e il PID del demone stesso. Il manifest dei tracepoint scritto a mano si trova in internal/abi/abi.yaml; la tabella runtime inserita nel repository viene generata in internal/abi/tracepoints_gen.go. Dopo aver modificato collector.bpf.c, ricostruisci con make ebpf. Dopo aver modificato i metadati ABI in internal/abi/abi.yaml, esegui make generate e poi make ebpf se il layout dell'evento del kernel o la tabella dei tracepoint sono cambiati.

Limitazioni

• Solo registrazione x86_64 — BPF è compilato -D__TARGET_ARCH_x86 (#2). Le interrogazioni e i dati dimostrativi generati dal benchmark non richiedono supporto di registrazione Linux.
• Solo indirizzi IPv4 — le connessioni/bind IPv6 sono memorizzate senza indirizzo decodificato.
• I conteggi di byte sono la dimensione richiesta della syscall (sonda di ingresso); I/O corti/falliti sovrastimano; readv/writev/sendmsg/recvmsg riportano 0.
• fd→path copre fd ≤ 1024 e può attribuire erroneamente dopo un forte riutilizzo del PID; fd più alti vengono registrati senza percorso.

Sviluppo

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

Struttura: cmd/ltm punto di ingresso; tutto il resto sotto internal/ (abi, cli, daemon, collector, ebpf, storage, agent, diff, query).

Il generatore ABI/schema mantiene le definizioni degli eventi, il DDL di archiviazione, i metadati dei tracepoint e le strutture rivolte al kernel legati a un'unica fonte di verità: internal/abi/abi.yaml. È intenzionalmente simile nello spirito al flusso di lavoro Argument Clinic di CPython (sorgente): quando si aggiunge una nuova superficie di evento/modulo catturato, aggiorna il manifest e rigenera gli output registrati invece di modificare a mano i file Go o C derivati.

Documentazione: docs/ (ABI, CLI, file generati, interrogazione, registrazione, architettura, sicurezza). Regole per i contributori: AGENTS.md.