Kanıt bundle'ı

Bundle nedir

Bundle, çalışma alanının, yani incident'ı yaşayan servisin repo'sunun içindeki bir klasördür. Başka bir klasör belirtmezseniz incident/ kullanılır:

ivralo incident evidence/night-of-the-12th/

Altındaki her dosya kanıttır, dışındaki hiçbir şey kanıt değildir. ivralo bir bundle'ın içine hiçbir zaman yazmaz.

İçine neler konur

Incident açıkken nöbetçi mühendisin elinde ne varsa onu koyun:

incident/
  alert.md          alarmın tetiklendiği hâli
  app.log           o saatlerdeki servis logu
  deploy.log        neyin, ne zaman deploy edildiği
  metrics.csv       varsa birkaç seri
  notes.md          neden bilinmeden önce konuşulanlar

• Uygulama log'ları. Düz metin, JSON Lines, syslog (RFC 3164 ya da RFC 5424 zaman biçimleri) ve erişim log'ları okunur. Python, Java, Go ve Node stack trace'leri frame'lerinin biçiminden tanınır.
• Deploy log'u. İçinde revision= ya da commit= geçen satır bir deploy sayılır. Düz cümleyle yazılmış, bir zaman, deployed, rolled out ya da released gibi bir fiil ve bir commit ya da sürüm içeren satır da öyle: 10:01 checkout-service deployed commit 6ad91e2. Deploy yoksa zaman çizelgesi de olmaz.
• Metrikler. CSV ya da Markdown tablosu olarak kopyalanmış bir dashboard. Log'lar bir kaynağın tükendiğini gösterdiğinde okunur.
• Brief. Neyin sorulduğunu anlatan, en üst seviyede duran bir INCIDENT ya da README dosyası (.txt, .md, .rst ya da uzantısız). İçindeki cümleler talimat olarak değil, bundle'ın brief'i olarak ele alınır; bkz. Kötü niyetli kanıt.

Varsa postmortem'i ya da düzeltmeyi bundle'a koymayın. Investigator bundle'daki her dosyayı okur.

Nasıl okunur

Bundle'daki bir yere referans, bundle'a göreli olarak dosya:satır ya da dosya:ilk-son biçiminde yazılır: app.log:160-170. Çalışma alanına göreli yazım (incident/app.log:160) da kabul edilir. Rapordaki her iddia satırları bu biçimde gösterir.

Neler reddedilir

ivralo incident daha işe başlamadan şunları reddeder ve nedenini stderr'de tek cümleyle yazar:

• link'ler çözüldükten sonra çalışma alanının dışında kalan bir bundle;
• çalışma alanının kendisi ya da onun üstündeki bir klasör;
• .ivralo/, .git/ ya da incident/.old/ gibi noktalı bir klasörden geçen bir yol;
• var olmayan ya da klasör olmayan bir yol;
• okunabilir hiçbir dosyası olmayan bir bundle;
• git repo'su olmayan bir çalışma alanı.

Bunların herhangi birinde komut 2 koduyla çıkar.

Git'in yok saydığı log'lar

Bundle genellikle git'in yok saydığı bir klasördür; servisin kendi logs/ klasörü de öyle. Incident aracı bundle'ı .gitignore'da ne yazarsa yazsın okur. Ama Investigator'ın arama araçları glob_files ve grep_files, git'in dosya listesini kullanır; yok sayılan bir klasörde kendi başlarına arama yapamazlar.

Bu tür klasörleri çalışma alanındaki IVRALO.md dosyasında # Evidence başlığı altında belirtin; her satıra bir yol ya da glob, çalışma alanına göreli:

# Evidence

- incident/
- logs/
- archive/*/checkout.log

Her kök çalışma alanının içinde kalmalıdır. /var/log/checkout/ gibi mutlak bir yol, .. ile dışarı çıkan bir yol ya da dışarıyı gösteren bir link kullanılmaz; ivralo doctor bunu sorun olarak bildirir.

Bir kökün yaptıkları ve yapmadıkları:

• Altındaki dosyaları glob_files ve grep_files'ın gördüğü dosyalara ekler; toplamda en fazla 50.000 dosya.
• Kapalı bir yolu asla açmaz. .env, .ivralo/ ve .git/ bir kökün içinde de kapalı kalır.
• Yalnızca güvendiğiniz bir klasörde dikkate alınır. Klonladığınız bir repo'nun IVRALO.md'si, modelin nerede arama yapacağına karar veremez.
• Hiçbir klasör varsayılan olarak kök sayılmaz, incident/ bile. Investigator'ın digest'i çıkarılan dosyalarda da arama yapmasını istiyorsanız onu da ekleyin.

ivralo doctor'ın evidence bölümü kökleri, her birinin kaç dosya eklediğini ve varsa sorunları listeler.

Investigator shell komutu çalıştırmaz. Bundle'ı kendi aracıyla, repo'yu da dosya ve kod araçlarıyla okur.

Alarmların yazdığı bundle'lar

Alarm alımı tetiklenen bir alarmı aldığında çalışma alanına tek dosyalık bir bundle yazar:

alerts/alertmanager-5a1f0c3e9b2d7e44-20261023T094315Z-7c/alert.md

Klasör adı kaynaktan, alarmın fingerprint'inden (PagerDuty'de incident'ın id'si), alındığı zamandan (UTC) ve iki rastgele hex basamaktan oluşur; böylece yeni bir teslimat önceki bir bundle'ın üzerine hiçbir zaman yazmaz. Dosyada alarmın adı ve durumu, kaynağı ve fingerprint'i, ne zaman başlayıp bittiği, ardından label'lar, annotation'lar, link'ler ve teslimata ait bölümler bulunur. Her değer gönderenin yazdığı metindir; her satırda bir alan olur ve 2000 karakterde kesilir. Link'ler metin olarak yazılır, hiçbir zaman açılmaz.

Bu stub sıradan bir bundle'dır. Klasörüne log'ları ya da bir deploy log'unu kopyalayıp onlarla yeniden inceleme yapabilirsiniz:

ivralo incident alerts/alertmanager-5a1f0c3e9b2d7e44-20261023T094315Z-7c/

Stub'lar .ivralo/ altında değil, çalışma ağacında durur; çünkü noktalı bir klasörün altındaki bundle hiçbir zaman kanıt sayılmaz. git status'ta görünmemeleri için alerts/'ı .gitignore'a ekleyin.