Add a prompt template for optimizing the `pack` step and a suite of Docker-based debug tools including build, run, and monitoring scripts. Enhance `pack_matrices` with LFD partition sizing and detailed timing reports, and update `stop` with additional system statistics. - Add `prompts/pack_optimization.md` to guide optimization of the `pack` step, specifying context, performance measurements, and deliverable structures. - Add `scripts/docker_debug/` infrastructure: Dockerfile for musl targets, `build.sh` for image creation, `run.sh` for parallel indexing and merging, `monitor.sh` for PID tracking, `gen_fasta.py` for synthetic genomes, and `gen_fasta_real.py` for real genome generation with `read_fna`. - Add `scripts/monitor_pack.sh` as a 1 Hz sampler for I/O and memory metrics, writing samples to CSV and summary reports. - Add `scripts/watch_merge.sh` to monitor process resource usage, enforcing memory limits via SIGTERM/SIGKILL guards based on VmRSS and VmSize. - Modify `src/obikindex/src/index/kmer_index.rs`: add `pending_matrix_bytes` and `report_pack_timings`; update `pack_matrices` to use LFD strategy for partition sizing and clarify documentation regarding `stat()` proxy bytes. - Modify `src/obisys/src/stage.rs`: update `stop` definition to include new variables (`user_secs`, `sys_secs`, faults, context switches, I/O blocks) and logic checking for swap usage.
62 lines
6.3 KiB
Markdown
62 lines
6.3 KiB
Markdown
# Prompt — où optimiser l'étape `pack` du merge (diagnostic d'abord)
|
|
|
|
> À coller tel quel au début d'une nouvelle session Claude Code ouverte à la racine du dépôt obikmer.
|
|
> Cette session est un **diagnostic** : elle produit une analyse chiffrée et des pistes classées, pas du code. Toute modification du code attend mon feu vert explicite, piste par piste.
|
|
|
|
---
|
|
|
|
## Contexte
|
|
|
|
`obikmer merge` se termine par une étape `finalize`, dont l'essentiel est `pack` : les matrices de présence/comptage, écrites en colonnes pendant le merge (`MatrixBuilder`), sont transposées en un format compact par partition (sparse par défaut). Le point d'entrée est `KmerIndex::finalize_indexed` (`src/obikindex/src/index/builder.rs`, étape « pack » vers la ligne 109), qui appelle `KmerIndex::pack_matrices(sparse)` (`src/obikindex/src/index/kmer_index.rs`). Les primitives sont dans `src/obicompactvec/src/` : `pack_bit_matrix` (`bitmatrix/packed.rs`), `pack_compact_int_matrix` (`intmatrix.rs`), `pack_sparse_compact_int_matrix` (`sparse_intmatrix.rs`), et le côté sparse des bits dans `bitmatrix/`.
|
|
|
|
Lis d'abord `DevDocMD/implementation/merge_scaling.md` (état du pack sparse : passage par une matrice dense séquentielle puis sparse, un seul mapping par partition) et `DevDocMD/implementation/merge_mmap_audit.md`.
|
|
|
|
## Mesure de référence (production, 2026-11-18)
|
|
|
|
Merge de 186 sources (`Cedrus`), 256 partitions, binaire glibc compilé localement, **192 CPU non contraints**, 17,5 milliards de k-mers nouveaux au total. Mode **présence**, compaction par défaut, donc **sparse** (pas de `--dense`) :
|
|
|
|
| Étape | Durée | Efficacité CPU | RSS max |
|
|
|---|---|---|---|
|
|
| `merge_partitions` | 748 s | 141×/192 (73 %) | 354 Go |
|
|
| `pack` | 231 s | 65×/192 (34 %) | **503,7 Go** |
|
|
|
|
La RAM de la machine est de 754 Go. Le RSS max est celui du process : il inclut les pages de fichiers mappés, pas seulement la mémoire anonyme. **Je n'ai pas encore séparé les deux.**
|
|
|
|
Progression de `pack` (partitions terminées par tranche de 10 %, début à 04:08:09) :
|
|
`+53 s` (10 %) · `+35 s` (20 %) · `+13 s` (30 %) · `+48 s` (40 %) · `+24 s` (50 %) · `+9 s` · `+6 s` · `+6 s` · `+6 s` · `+11 s` (100 %), puis `+20 s` avant la fin de l'étape. Les partitions les plus grosses passent en premier (tri décroissant dans `merge.rs`), mais je ne sais pas si `pack` les traite dans le même ordre ni si l'ordre est le bon.
|
|
|
|
## Ce que je veux savoir
|
|
|
|
1. **Où part le temps** de `pack` ? Lecture des colonnes, transposition, écriture, `sync`/`fsync`, attente d'un verrou, déséquilibre entre partitions ? Efficacité de 34 % sur 192 workers : qu'est-ce qui les bloque ?
|
|
2. **Où part la mémoire** (504 Go) ? Combien est de la mémoire anonyme, combien des pages de fichiers mappés ? Est-elle proportionnelle au nombre de workers ? Quelle est la mémoire vivante par partition en cours de `pack` ?
|
|
3. **Quel est le parallélisme réel** : combien de partitions `pack` traite-t-il en même temps, et qu'est-ce qui le fixe (`PartitionRunner`, `--cpu-max`, NUMA) ?
|
|
4. Y a-t-il du **travail inutile** (relectures, copies intermédiaires, colonnes vides ou toutes-absentes ré-écrites, étape dense qui pourrait être évitée) ?
|
|
|
|
## Méthode (impérative)
|
|
|
|
- **Lire et mesurer avant de proposer.** Pas de récit plausible sans preuve : tout ce qui n'est pas vérifié par lecture du code ou par mesure est marqué « hypothèse ».
|
|
- Pour mesurer sans la production : `scripts/docker_debug/` fournit un conteneur Linux (build glibc ou musl) qui lance un merge de N sources synthétiques ou dérivées de génomes réels (`run.sh`, variables `GEN`, `REAL`, `GENOME_LEN`, `TARGET`, `TOOL=heaptrack` pour glibc) avec un moniteur CSV de mappings et de RSS. Les génomes de 2 Mb donnent des partitions assez grosses pour que `pack` ait quelque chose à faire. `heaptrack` fonctionne sur le build glibc (pas sur le build musl statique). `gdb` ne fonctionne pas sous Rosetta.
|
|
- Pour séparer mémoire anonyme et fichiers mappés, utilise `/proc/PID/status` (`RssAnon`, `RssFile`, `RssShmem`), **jamais `smaps` en entier** sur un process à beaucoup de mappings (il verrouille `mmap_lock` et ralentit le process).
|
|
- Les estimations de coût (octets, secondes) sont marquées **estimées** ; les chiffres observés sont marqués **mesurés**.
|
|
|
|
## Règles du projet (non négociables)
|
|
|
|
- Avant tout travail de code : `mcp__serena__initial_instructions`, puis Serena (`find_symbol`, `get_symbols_overview`, `find_referencing_symbols`) pour naviguer. `rust-analyzer-mcp` et `qmd` quand ils servent. Consulte `context7` avant d'utiliser une API de bibliothèque externe.
|
|
- **Aucune commande VCS mutante** (git/jj : commit, add, mv, rm, describe, push…). Lecture seule autorisée.
|
|
- **Aucune nouvelle dépendance, aucun changement de version** sans mon accord explicite. Si un problème de bibliothèque se pose, expose-le et propose des alternatives.
|
|
- **Une question appelle une réponse, pas une action.** Ne modifie aucun fichier de `src/` sans demande explicite. Cette session est en lecture seule sur le code.
|
|
- Le code existant est une hypothèse, pas une vérité : signale tout ce qui est devenu injustifié plutôt que de le garder par inertie.
|
|
- Si tu proposes d'ajouter une opération à une structure partagée, mets-la comme méthode générique sur cette structure (crate `obicompactvec`), pas comme fonction libre dans le consommateur.
|
|
- Ne jamais matérialiser en mémoire une structure volumineuse qui peut être streamée.
|
|
- Échanges en **français**, documentation en **anglais**.
|
|
|
|
## Livrable
|
|
|
|
Un rapport (dans la conversation, pas dans un fichier, sauf si je le demande) avec :
|
|
1. Le chemin de code de `pack`, de `finalize_indexed` jusqu'aux écritures disque, résumé en quelques lignes par étape.
|
|
2. Pour chaque question ci-dessus : ce qui est **mesuré**, ce qui est **hypothèse**, et comment vérifier l'hypothèse.
|
|
3. Une liste de **pistes d'optimisation classées** par gain attendu/coût/risque. Pour chaque piste : ce qu'elle changerait, ce qu'elle risque, et comment on verrait qu'elle marche. Aucune implémentation.
|
|
4. Les vérifications de non-régression à prévoir : le résultat sur disque doit rester **identique octet pour octet** (voir les oracles `scripts/smoke_test_merge.sh` et `scripts/bench_merge_oracle.sh`).
|
|
|
|
Termine par la question : « Quelle piste veux-tu que j'implémente ? » et attends ma réponse.
|