Dokümantasyon / Incident'lar

Raporu okumak

Bir incident raporunda neler bulunur ve nasıl okunur: kodun hesapladığı bulgular, Investigator'ın verdiği tek yargı, sonucun nasıl belirlendiği ve kendi araçlarınızda kullanmanız için Markdown'ın yanında duran JSON dosyaları.

Nerede

Her inceleme bir klasör yazar:

.ivralo/incidents/incident-20261012-101500/
  digest.json     gerçekler, herhangi bir model bir şey okumadan önce kodun hesapladığı
  report.json     veri olarak rapor
  report.md       insanlar için rapor

.ivralo/ git tarafından yok sayılır; bu dosyaların hiçbiri bir commit'e girmez. ivralo'nun kendi kimlik bilgileri, iki rapor dosyası da yazılmadan önce gizlenir. Ama log'ların içindeki bir secret, örneğin bir istek satırındaki token, yine de alıntılanabilir.

Digest: kodun hesapladığı bulgular

Investigator daha hiçbir şey okumadan, kod bundle'ı bir digest'e çevirir. Rapordaki her sayı buradan gelir.

Bölüm	İçeriği
İmzalar	Her hata, satırdan satıra değişen kısımları (id'ler, sayılar, tırnak içindeki değerler, zaman damgaları) ayıklanmış metniyle ve stack frame'leriyle gruplanır. Hata veren 340 satır, sayısı, ilk ve son görüldüğü an, endpoint'leri ve bir örneğiyle birlikte tek bir imzaya dönüşür.
Zaman çizelgesi	Bundle'da bulunan deploy'lar ve her imza için: son deploy'dan kaç dakika sonra başladığı, hata sürerken bir deploy yapılıp yapılmadığı ya da herhangi bir deploy'dan önce başlayıp başlamadığı.
Revizyon ve şüpheliler	Repo'da deploy edilen commit'in olup olmadığı, o deploy'un neyi değiştirdiği (diff'iyle birlikte), stack frame'lerinin hangi dosyaları gösterdiği, bu dosyaların repo'da olup olmadığı, bir frame'in bastığı satırın repo'daki aynı numaralı satırla aynı olup olmadığı ve hangi dosyaların hem bir trace'te geçip hem de deploy'la değiştiği.
Tükenme ipucu	Bir satır, sürecin kendi sınırına dayandığını söylüyorsa (bellek yetersiz, diskte yer kalmadı, çok fazla açık dosya ya da istemci, bir pod'un `OOMKilled` olması): önceki beş dakikada istek gelen route'lar, kaynağın ve trafiğin metriklerde nasıl değiştiği ve kod indeksi varsa her route'u sunan dosyalar. Bir sınırın ayarlanmış olması, o sınıra ulaşıldığı anlamına gelmez.
Bildirilen bağlam	Brief'te ya da bir notta adı geçen sayfalar ve route'lar, her biri kaynağıyla.
Not established	Digest'in karara bağlayamadığı şeyler; örneğin repo'da bulunmayan bir deploy.

Lead, incelemenin çıkış noktası olan imzadır. Digest'teki her liste, neyi dışarıda bıraktığını da belirtir.

Yargı

Investigator digest'i ve digest'in gösterdiği kodu okur, sonra iki şeye karar verir:

sınıf: code, config, data, infrastructure, external ya da ambiguous;
neden, ve kanıtların bu nedeni kanıtlayıp kanıtlamadığı (established).

Bir nedenin "kanıtlanmış" sayılması için ne gerektiği sınıfa göre değişir:

Sınıf	Kanıtlar şunu gösteriyorsa kanıtlanmıştır
`code`	Repo'da bulunan ve kodu, alıntılanan bir satırın gösterdiği davranışı üreten bir dosya. Log satırlarının bu dosyanın adını vermesi gerekmez; eşleşmeyi siz değerlendirebilin diye rapor, repo'daki satırı kanıtın yanına basar.
`config`	Ayarın adını ve değiştiğini ya da eksik olduğunu gösteren bir satır.
`data`	Kaydın kendisi ve ihlal ettiği kural.
`infrastructure`	Kaynak ve durumu.
`external`	Sağlayıcının kendi satırı.

Her sınıf, bundle'dan en az bir alıntılanmış satır ister. Investigator kaydını tek bir araçla, file_incident_report ile yapar; bu araç her referansı bundle'da ve repo'da kontrol eder. Çözülemeyen bir referans reddedilir ve Investigator kaydı yeniden yapar.

Araç, nedende geçen miktar ifadelerini de digest'teki sayılarla karşılaştırır. Digest başka bir endpoint'te de hata sayarken "Tüm hatalar GET /api/orders üzerinde" demek, bozuk bir referans gibi reddedilir. Sayıların desteklemediği "çoğu" ya da "birkaç" gibi ifadeler kaydedilir; ama nedenin kanıtlanmış sayılıp sayılmayacağını da sonucu da değiştirmez. ivralo bunu, hesaplanan sayılarla birlikte Not established altında not eder.

Sonuç

Yargıyı tek bir sonuca model değil, kod çevirir. Kurallar şu sırayla uygulanır:

Investigator okuyana yönelik bir satır bildirdiyse: ESCALATED.
Sınıf config, data, infrastructure ya da external ise, kanıtlanmışsa ve en az bir alıntılanmış satır varsa: NOT_CODE_ISSUE.
Sınıf code ise, kanıtlanmışsa, alıntılanmış bir satır ve repo'da bulunan en az bir şüpheli dosya varsa: DIAGNOSED.
ambiguous dahil geri kalan her durumda: INSUFFICIENT_EVIDENCE.

Güven yüzdesi yoktur. Repo'da deploy edilen revizyonun olup olmadığı bir bulgu olarak bildirilir ve hiçbir sonucu değiştirmez.

report.md, bölüm bölüm

Bölüm	İçeriği
Outcome	Tek satır: sonuç ve sınıf, örneğin `DIAGNOSED - class code`. `ESCALATED`'in sınıfı olmaz.
Observed	Hesaplanan bulgular, her satırda bir tane, her birinin sonunda kaynağı: `app.log:160-170`, `deploy.log:3`, bir commit.
Inferred	Sınıf ve neden, ikisi de çıkarım olarak işaretli; şüpheli dosyalar ve alıntılanan satırlar. Bunları modelin metninden değil, bundle'dan kod kopyalar. Şüpheli bir dosya için repo'daki o satırın kodu da basılır.
Hypotheses	Yalnızca Investigator bir defter tuttuysa görünür (aşağıda).
Not established	Kanıtların karara bağlayamadığı şeyler. Her satır, kimin yazdığını belirtir: `(code)` ya da `(investigator)`.
Instructions found in the evidence	Yalnızca böyle satırlar varsa görünür: her satır alıntılanır ve uygulanmadığı belirtilir, ya da bir kenara konduysa "not an instruction to the reader" diye işaretlenir. Bkz. Kötü niyetli kanıt.
Evidence index	Raporun kullandığı bütün referanslar.

Sayılar, zamanlar ve aralıklar yalnızca Observed bölümünde ve ivralo'nun Not established altındaki kendi satırlarında görünür. "Deploy hatalardan önce yapıldı" gözlenmiş bir bulgudur; neden ise bir çıkarımdır ve bunu açıkça belirtir.

Hipotez defteri

Rapor tek bir neden söyler. İsteğe bağlı defter (ledger) ise Investigator'ın başka hangi ihtimalleri tarttığını gösterir; böylece raporu inceleyen kişi neyin elendiğini görür, INSUFFICIENT_EVIDENCE ile biten bir rapor da hangi ihtimallerin açık kaldığını söyler.

Durum	Anlamı	Alıntılanmış satır gerekir mi
validated	Kanıtlar bunu gösteriyor.	evet
invalidated	Kanıtlar bunun öyle olmadığını gösteriyor.	evet
inconclusive	Tartıldı, ama kanıtlar iki yönde de karar vermeye yetmiyor.	hayır
checked healthy	Bakılan ve sağlıklı bulunan bir bileşen.	evet
not checked	Adı geçti ama bakılmadı.	hayır

Satır gerektirdiği halde hiç satır göstermeyen ya da çözülemeyen bir satır gösteren kayıt deftere alınmaz; hangisinin neden alınmadığı Not established altında yazar. Defter en fazla 20 kayıt tutar. Sonucu hiçbir zaman değiştirmez, yalnızca açıklar.

ivralo why -s <id> last "the database was down" tek bir hipotezi dayandığı satırlara kadar takip eder.

report.json

Aynı raporun veri hali. Başlıca anahtarlar:

Anahtar	İçeriği
`format`	Biçim sürümü, `1`.
`incident`	Incident id'si, yani klasörün adı.
`outcome`, `class`, `established`	Sonuç, sınıf ve nedenin kanıtlanıp kanıtlanmadığı.
`bundle`, `digest`	Bundle'ın yolu ve `digest.json`'ın yolu.
`lead`	Lead imzası: `id`, `text`, `count`, `first`, `last`, `kind` (`exhaustion` ya da boş).
`signatures`, `timeline`	Her imza (`id`, `level`, `count`, `text`) ve her an (`time`, `kind`, `label`, `ref`).
`deploy`, `revision`	Lead'in karşılaştırıldığı deploy ve repo'da onun commit'inin olup olmadığı (`held`).
`changed`, `changed_range`, `on_trace_and_changed`, `frames`	Deploy'un neyi değiştirdiği ve stack frame'lerinin repo ile nasıl karşılaştırıldığı.
`suspects`	Şüpheli dosyalar: `path`, `line`, `held`, `note`, `code`.
`cause`, `evidence`, `commits`	Neden ve alıntılanan her referans, bundle'dan kopyalanmış `lines` ile birlikte.
`hostile`, `set_aside`	Okuyana yönelik satırlar ve talimat sayılmayıp bir kenara konan satırlar.
`hypotheses`	Defter; yoksa `[]`.
`not_established`	`{"by": "code" or "investigator", "text": ...}` biçimindeki kayıtlar.
`run_id`, `session_id`, `model`, `filed_at`	Kaydı hangi çalıştırmanın, hangi oturumda, hangi modelle ve ne zaman (UTC) yaptığı.

digest.json

Digest'in tamamı; raporda olandan fazlasını içerir: bundle (her dosyanın boyutu, satır sayısı ve okunup okunmadığı), frame'leri ve endpoint'leriyle signatures, deploys, moments, placements (her imzanın kendinden önceki deploy'a uzaklığı), correlation (deploy'un diff'i dahil repo bulguları), reported_context, limits (her listenin ne kadarını gösterdiği) ve not_established.

Sonuç için report.json'ı, Investigator'a tam olarak ne verildiğini görmeniz gerektiğinde de digest.json'ı kullanın.