Guide

Première analyse

Une analyse parcourt un dossier et affiche ce qu'elle a trouvé. Rien n'est enregistré, rien n'est modifié.

$ spacetrace scan ~/projects
scanned 84,213 entries in 1.9s
total 12.4 GiB logical · 12.7 GiB on disk
3 paths could not be read

Les chemins illisibles sont comptés et échantillonnés au lieu d'arrêter le parcours. Sur macOS, sortir de votre dossier personnel exige le Full Disk Access pour votre terminal ; sans lui, l'analyse se termine quand même et vous dit ce qu'elle a manqué.

La rendre plus rapide et plus étroite

spacetrace scan / -x
spacetrace scan ~/code --exclude node_modules --exclude .git
spacetrace scan /var --depth 3
spacetrace scan /srv --no-dedupe

--exclude prend un nom de répertoire, pas un chemin, et se répète. On ne descend jamais dans les dossiers exclus : exclure node_modules sur une machine de développement fait généralement la différence entre deux secondes et trente.

Instantanés et comparaison

C'est la partie que les autres analyseurs n'ont pas. Enregistrez une analyse, enregistrez-en une autre plus tard, et demandez ce qui a changé entre les deux.

$ spacetrace scan /srv --save --label weekly
saved snapshot #1

$ spacetrace scans
 ID  WHEN              HOST     ROOT   LABEL    TOTAL
  2  2026-09-06 19:40  srv-01   /srv            76.3 MiB
  1  2026-09-06 17:23  srv-01   /srv   weekly   23.8 MiB

Puis comparez. Sans argument, il prend les deux derniers.

$ spacetrace diff --path /srv
#1 2026-09-06 17:23 [weekly]  →  #2 2026-09-06 19:40
total 23.8 MiB → 76.3 MiB   (+52.5 MiB)

      CHANGE  STATUS          NEW  PATH
   +40.1 MiB  grew       42.9 MiB  app/logs/
   +14.3 MiB  grew       25.7 MiB  backups/
    -1.9 MiB  removed         0 B  uploads/

Contre le disque tel qu'il est maintenant

Vous n'avez pas besoin de deux instantanés. Comparez le plus récent avec une analyse en direct :

Choisir ce qui apparaît

spacetrace diff --path /srv --min 10M
spacetrace diff --path /srv --files
spacetrace diff 3 7

Empêcher la base de grossir indéfiniment

spacetrace prune --path /srv --keep 30
spacetrace rm 4

Parcourir une analyse

ls liste les dossiers par taille, depuis une analyse en direct ou depuis un instantané enregistré.

spacetrace ls /var/lib --top 20
spacetrace ls --scan 3 --subpath docker/overlay2

Pour passer un instantané à autre chose, export écrit le format de ncdu :

Chaque commande accepte aussi --json, qui est la manière prise en charge de scripter par-dessus. Les colonnes lisibles peuvent changer ; la forme du JSON, non.

L'agent sur un serveur

spacetrace-agent est le même code sous forme de service : il analyse selon un calendrier les racines que vous configurez, conserve les instantanés et répond via HTTP. C'est un binaire statique, et il ne fait que lire — il n'existe en lui aucun chemin de code qui supprime quoi que ce soit en dehors de sa propre base d'instantanés.

1. Écrivez une configuration et un jeton

   spacetrace-agent init > /etc/spacetrace/agent.tomlCopier
   head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > /etc/spacetrace/token && chmod 600 /etc/spacetrace/tokenCopier

   serve refuse de démarrer sans jeton. Un agent sans authentification livre l'inventaire complet de son système de fichiers à quiconque atteint le port.

2. Dites quoi analyser et quand

   db = "/var/lib/spacetrace/snapshots.sqlite"
   utc_offset_minutes = 0
   
   [server]
   listen = "127.0.0.1:7878"
   token_file = "/etc/spacetrace/token"
   
   [[roots]]
   path = "/var"
   schedule = "0 3 * * *"
   label = "nightly"
   exclude = ["node_modules", ".git"]
   one_file_system = true
   keep = 14

   Cinq champs cron, avec *, a-b, */n et des listes. Pas de secondes, pas de @daily. Les clés de configuration inconnues sont refusées au démarrage, car une faute de frappe qui ne fait rien en silence sur une machine que personne ne regarde est pire qu'un refus de démarrer.

3. Vérifiez avant de le lancer

   $ spacetrace-agent --config /etc/spacetrace/agent.toml check
   config       ok
   database     /var/lib/spacetrace/snapshots.sqlite
   host         nas
   listen       127.0.0.1:7878
   token        configured
   ad-hoc scans refused
   
   ROOT                          SCHEDULE        NEXT RUN
   /var                          0 3 * * *       2026-09-09 03:00
   
   Times are UTC.

   Un calendrier qui ne peut jamais se déclencher affiche never au lieu d'échouer en silence.

4. Lancez-le

   systemctl enable --now spacetrace-agentCopier

   L'unité systemd fournie exécute l'agent sous son propre utilisateur non privilégié avec ProtectSystem=strict, à Nice=10 et en priorité d'E/S idle. Une analyse ne doit jamais gêner ce à quoi la machine sert vraiment.

   Sous Docker, montez l'hôte en lecture seule et analysez-le :

   docker run -d --name spacetrace \
     -v /:/host:ro \
     -v spacetrace-data:/var/lib/spacetrace \
     -v /etc/spacetrace:/etc/spacetrace:ro \
     -p 7878:7878 \
     ghcr.io/unalcakir28/spacetrace

Avant de l'exposer

• Il écoute sur la boucle locale par défaut. Publier l'inventaire d'un système de fichiers sur un réseau doit être une décision délibérée.
• Il n'y a pas de TLS dans l'agent. Mettez un reverse proxy devant.
• Le jeton est comparé sans sortie anticipée : un mauvais jeton met le même temps à être rejeté, quelle qu'en soit la part correcte.
• /health n'exige aucun jeton, donc un healthcheck de conteneur fonctionne, et ne renvoie que l'état et la version — aucun nom d'hôte, aucune racine.
• Les analyses à la demande sont désactivées. Activées, quiconque détient le jeton peut énumérer tout répertoire lisible par l'utilisateur de l'agent.

Lire une autre machine

Toute commande en lecture seule accepte --remote. Rien de nouveau à apprendre : les mêmes sous-commandes, pointées ailleurs.

export SPACETRACE_TOKEN=…

spacetrace --remote https://nas.example.com scans
spacetrace --remote https://nas.example.com diff --path /var
spacetrace --remote https://nas.example.com ls --top 20
spacetrace --remote https://nas.example.com pull --root /var

Enregistrez un serveur distant pour ne plus taper l'URL et le jeton — dans ~/.config/spacetrace/remotes.toml :

[remotes.nas]
url = "https://nas.example.com"
token = "…"

curl -H "Authorization: Bearer $SPACETRACE_TOKEN" \
  https://nas.example.com/scans/7/download -o snap.sqlite
spacetrace --db snap.sqlite scans

scan, prune et rm refusent de tourner avec --remote : ils agissent sur l'état local, et l'agent ne supprime rien.

Quelle taille, et pourquoi

Chaque entrée porte deux nombres, et aucun n'est une estimation de l'autre.

Elles divergent dans les deux sens et les deux sont justes. Un fichier d'un octet alloue un bloc entier : sur le disque, il est plus gros que sa longueur. Un fichier creux déclare une longueur qu'il n'a jamais allouée : une image disque peut déclarer un téraoctet et n'en occuper que dix-neuf gigaoctets.

Les fichiers creux sont la raison pour laquelle l'application choisit sur le disque par défaut. Les images de machines virtuelles, les fichiers de base de données et les core dumps figurent parmi les plus grosses entrées de tout disque réel : la mesure logique se trompe donc le plus sur les entrées qui comptent le plus. La ligne de commande utilise logique par défaut, et les deux disent laquelle elles affichent.

La capacité est rapportée comme libre sur total, jamais comme « % utilisé ». Sur un système de fichiers dont l'espace est partagé entre volumes — conteneur APFS, sous-volumes btrfs, LVM thin — un chiffre d'espace utilisé inclurait les voisins et contredirait df sur le même point de montage.

Les liens physiques sont comptés une seule fois par défaut ; la seconde copie apparaît dans l'arbre avec une contribution de zéro octet. Les liens symboliques ne sont jamais suivis et comptent pour leur propre taille.

Référence des commandes

spacetrace scan PATH

--save, --label

spacetrace scans

—

spacetrace diff

--path, --since-last, ID ID

spacetrace ls PATH

--top, --scan, --subpath

spacetrace export

--scan, --out

spacetrace pull --root PATH

--remote

spacetrace prune / rm

--keep, ID

spacetrace-agent init

—

spacetrace-agent check

—

spacetrace-agent serve

—

spacetrace-agent push URL

--root, --token

Options valables sur la plupart des commandes

• --exclude NAME
• -x, --one-file-system
• --depth N
• --min SIZE
• --files
• --no-dedupe
• --json
• --db PATH
• --remote NAME|URL

Où les choses sont conservées

L'application de bureau écrit dans la même base : un instantané enregistré dans l'application apparaît dans spacetrace scans, et inversement.

Limites connues

Publiées plutôt que découvertes. Si vous en rencontrez une, c'est une dette connue, pas une surprise.

• Sous Windows, la taille sur le disque égale la taille logique et la déduplication des liens physiques est désactivée. Les vrais chiffres exigent GetFileInformationByHandleEx et FileIdInfo.
• Les clones APFS ne sont pas dédupliqués, et sur btrfs ou ZFS les reflinks et la compression font qu'un parcours d'arbre ne peut pas rapporter l'usage réel. Aucun parcours d'arbre ne peut ; les nombres sont ceux des fichiers.
• Une analyse garde tout l'arbre en mémoire. Le profil mémoire au-delà de dix millions de fichiers n'a pas été mesuré.
• L'agent n'a ni TLS ni limitation de débit. Utilisez un reverse proxy ; le jeton est déjà obligatoire.
• Le planificateur n'a pas de base de fuseaux horaires — UTC plus un décalage fixe : les changements d'heure restent à votre charge.

docs/AGENT.md