Kılavuz

İlk tarama

Tarama bir klasörü yürüyor ve bulduğunu basıyor. Hiçbir şey saklanmıyor, hiçbir şey değişmiyor.

$ 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

Okunamayan yollar yürüyüşü durdurmak yerine sayılıyor ve örnekleniyor. macOS'ta ana dizinin dışına uzanmak için terminaline Full Disk Access gerekiyor; o olmadan da tarama tamamlanıyor ve neyi kaçırdığını söylüyor.

Daha hızlı ve daha dar yapmak

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

--exclude bir yol değil bir dizin adı alıyor ve tekrarlanabiliyor. Hariç tutulan klasörlerin içine hiç inilmiyor; yani bir geliştirici makinesinde node_modules'ü hariç tutmak genellikle iki saniye ile otuz saniye arasındaki fark.

Anlık görüntüler ve karşılaştırma

Diğer analizcilerde olmayan kısım bu. Bir taramayı sakla, sonra bir tane daha sakla ve aralarında neyin değiştiğini sor.

$ 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

Sonra karşılaştır. Argüman verilmezse son ikisini alıyor.

$ 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/

Diskin şu anki hâline karşı

İki anlık görüntüye ihtiyacın yok. En yenisini canlı bir taramayla karşılaştır:

Neyin görüneceğini seçmek

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

Veritabanının sonsuza kadar büyümesini engellemek

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

Bir taramayı gezmek

ls klasörleri boyuta göre listeliyor; ya canlı bir taramadan ya da saklanmış bir anlık görüntüden.

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

Bir anlık görüntüyü başka bir şeye vermek için export ncdu'nun kendi biçimini yazıyor:

Her komut ayrıca --json alıyor; betikleme için desteklenen yol bu. İnsan tarafından okunan kolonlar değişmekte serbest, JSON şekli değil.

Sunucuda ajan

spacetrace-agent aynı kodun servis hâli: yapılandırdığın kökleri zamanlanmış olarak tarıyor, anlık görüntüleri tutuyor ve HTTP üzerinden cevap veriyor. Tek statik ikili, ve yalnızca okuyor — içinde kendi anlık görüntü veritabanının dışında bir şeyi silen hiçbir kod yolu yok.

1. Bir yapılandırma ve token yaz

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

   serve token olmadan başlamayı reddediyor. Kimlik doğrulaması olmayan bir ajan, bütün dosya sistemi envanterini o porta ulaşabilen herkese teslim eder.

2. Neyi ne zaman tarayacağını söyle

   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

   Beş cron alanı; *, a-b, */n ve listelerle. Saniye yok, @daily yok. Bilinmeyen yapılandırma anahtarları açılışta reddediliyor, çünkü kimsenin izlemediği bir makinede sessizce hiçbir şey yapmayan bir yazım hatası, açılmayı reddetmekten kötüdür.

3. Başlatmadan önce kontrol et

   $ 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.

   Hiç tetiklenemeyecek bir zamanlama sessizce başarısız olmak yerine never diyor.

4. Çalıştır

   systemctl enable --now spacetrace-agentKopyala

   Birlikte gelen systemd birimi ajanı kendi yetkisiz kullanıcısı olarak ProtectSystem=strict altında, Nice=10 ve boşta I/O önceliğiyle çalıştırıyor. Bir tarama, makinenin asıl işine hiç engel olmamalı.

   Docker'da ana makineyi salt okunur bağla ve onu tara:

   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

Dışa açmadan önce

• Varsayılan olarak loopback dinliyor. Bir dosya sistemi envanterini ağa yayınlamak bilinçli bir düzenleme olmalı.
• Ajanda TLS yok. Önüne bir ters vekil koy.
• Token erken çıkış olmadan karşılaştırılıyor; yani yanlış bir token, ne kadarı doğru olursa olsun aynı sürede reddediliyor.
• /health token istemiyor, böylece konteyner sağlık kontrolü çalışıyor; yalnızca durum ve sürüm dönüyor — sunucu adı yok, kök yok.
• Anlık istek üzerine tarama kapalı. Açıkken, tokenı elinde tutan herkes ajanın kullanıcısının okuyabildiği her dizini listeleyebilir.

Başka bir makineyi okumak

Salt okunur her komut --remote alıyor. Yeni bir şey öğrenmek gerekmiyor: aynı alt komutlar, başka yere yönlenmiş.

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

Adres ve tokenın yazılmaktan çıkması için bir uzak kaynak kaydet — ~/.config/spacetrace/remotes.toml içinde:

[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 ve rm --remote ile çalışmayı reddediyor: yerel durum üzerinde iş yapıyorlar ve ajan hiçbir şeyi silmiyor.

Hangi boyut, ve neden

Her girdi iki sayı taşıyor ve hiçbiri diğerinin tahmini değil.

İki yöne de ayrışıyorlar ve ikisi de doğru. Bir baytlık dosya bütün bir blok tahsis ediyor, yani diskte uzunluğundan büyük. Seyrek bir dosya hiç tahsis etmediği bir uzunluk bildiriyor: bir disk imajı bir terabayt iddia edip on dokuz gigabayt tutabiliyor.

Uygulamanın varsayılanının diskte olmasının sebebi seyrek dosyalar. Sanal makine imajları, veritabanı dosyaları ve çekirdek dökümleri gerçek her diskteki en büyük girdiler arasında; yani mantıksal ölçü tam da en çok önemli olan girdilerde en çok yanılıyor. Komut satırının varsayılanı mantıksal ve ikisi de hangisini gösterdiğini söylüyor.

Kapasite “% dolu” olarak değil, toplamın boşu olarak raporlanıyor. Alanı birimler arasında paylaşılan bir dosya sisteminde — APFS konteyneri, btrfs alt birimleri, ince LVM — kullanılan bir rakam kardeşleri de içerir ve aynı bağlama noktası için df ile çelişir.

Sabit bağlantılar varsayılan olarak bir kez sayılıyor; ikinci kopya ağaçta sıfır bayt katkıyla görünüyor. Sembolik bağlantılar hiç izlenmiyor ve kendi boyutlarıyla sayılıyor.

Komut başvurusu

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

Çoğu komutta çalışan seçenekler

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

Neyin nerede tutulduğu

Masaüstü uygulaması aynı veritabanına yazıyor; yani uygulamada kaydedilen bir anlık görüntü spacetrace scans içinde görünüyor, tersi de geçerli.

Bilinen eksikler

Keşfedilmesi beklenmeden yayınlandı. Bunlardan birine denk gelirsen bilinen borç, sürpriz değil.

• Windows'ta diskteki boyut mantıksal boyuta eşit ve sabit bağlantı tekilleştirmesi kapalı. Gerçek rakamlar için GetFileInformationByHandleEx ve FileIdInfo gerekiyor.
• APFS klonları tekilleştirilmiyor; btrfs veya ZFS'te reflink ve sıkıştırma yüzünden bir ağaç yürüyüşü gerçek kullanımı raporlayamıyor. Hiçbir ağaç yürüyücüsü yapamaz; sayılar dosyaların kendi sayıları.
• Tarama bütün ağacı bellekte tutuyor. On milyon dosyanın üstündeki bellek profili ölçülmedi.
• Ajanda TLS ve hız sınırlama yok. Ters vekil kullan; token zaten zorunlu.
• Zamanlayıcıda saat dilimi veritabanı yok — UTC artı sabit bir offset, yani yaz saati kaymalarını düşünmek sana kalıyor.

docs/AGENT.md