Dokümantasyon / Incident'lar

Kendi incident'larınızda pilot

Investigator'a canlı bir incident emanet etmeden önce onu ekibinizin daha önce çözdüğü incident'larla deneyin. ivralo pilot run her birini yalnızca kanıtlarına bakarak inceler ve raporu mühendislerinizin bulduğu nedenle karşılaştırıp puanlar. Hepsi sizin makinenizde olur.

Pilot ne işe yarar

Çözülmüş on kadar incident hazırlayın. Her biri için kanıt bundle'ı, servisin o sırada çalıştığı revizyon ve mühendislerinizin bulduğu neden gerekiyor. Sonra şunu çalıştırın:

ivralo pilot run ~/ivralo-pilot

/home/ops/ivralo-pilot/.pilot/20261023-093000/pilot.md
7 of 10 incidents matched the known cause (2 missed, 1 no report, 0 not run)

ivralo her incident için repo'nuzu o incident'ın revizyonunda sıfırdan klonlar, bundle'ı klonun içine kopyalar ve Investigator'ı tam olarak ivralo incident gibi çalıştırır. Bilinen nedeni ancak inceleme bittikten sonra okur ve yazılan raporu onunla karşılaştırıp puanlar.

Puan; sonucu, sınıfı ve raporda geçen dosyaları kontrol eden sabit bir hesapla çıkar. Hiçbir model değerlendirme yapmaz, cümleler karşılaştırılmaz. Böylece elinize kendi incident'larınız üzerinde kendiniz kontrol edebileceğiniz bir doğruluk oranı geçer.

Paket

Paket (pack), her incident için bir alt klasör içeren bir klasördür. Alt klasörün adı, incident'ın rapordaki adı olur:

ivralo-pilot/
  2026-03-checkout-500s/
    bundle/              kanıtlar
    revision             tek satır: servisin çalıştırdığı commit
    known-cause.yaml     mühendislerinizin bulduğu
  2026-05-ledger-pool/
    bundle/
    revision
    known-cause.yaml

Adı noktayla başlayan klasörler ve paketin en üst dizinindeki dosyalar (örneğin kendi README'niz) atlanır.

Girdi	Nedir
`bundle/`	`incident/` altındakilerle aynı kurallarla okunan bir kanıt bundle'ı. Incident açıkken nöbetçi mühendisin elinde ne varsa onu koyun: log'lar, deploy log'u, alarm, neden bulunmadan önce alınan notlar.
`revision`	Boş olmayan tek bir satır: incident sırasında servisin çalıştığı commit sha'sı, tag ya da branch. Harf ya da rakamla başlar; harf, rakam ve `. _ / + -` içerebilir; en fazla 200 karakterdir ve hiçbir zaman `..` içermez.
`known-cause.yaml`	Mühendislerinizin vardığı sonuç, aşağıdaki anahtarlarla.

Postmortem'i, düzeltmeyi ve sonradan yazılan her şeyi bundle/ dışında tutun. Bunlar cevabın kendisi ve Investigator bundle'daki her dosyayı okur. ivralo bir postmortem'i bir log'dan ayırt edemez.

known-cause.yaml

cause: >
  The 14:02 deploy dropped the upper-casing of coupon codes in parse(); every
  lower-case code raised KeyError in pricing.
outcome: DIAGNOSED
class: code
cites: [src/svc/parsing.py]
never_cites: [src/svc/legacy.py]

Anahtar	Zorunlu	Anlamı
`cause`	evet	Mühendislerinizin kendi ifadesi. Pilot raporunda Investigator'ın bulduğu nedenin yanında gösterilir, hiçbir zaman puanlanmaz.
`outcome`	evet	`DIAGNOSED`, `NOT_CODE_ISSUE`, `INSUFFICIENT_EVIDENCE` ya da `ESCALATED`.
`class`	hayır	`code`, `config`, `data`, `infrastructure`, `external` ya da `ambiguous`. Verilirse raporun da aynı sınıfı bulması gerekir.
`cites`	hayır	Doğru bir raporda geçmesi gereken dosyalar.
`cites_any`	hayır	İki dosyaya yayılan bir neden: raporda en az birinin geçmesi gerekir.
`never_cites`	hayır	Suçlu gibi görünen ama suçlu olmayan dosyalar: raporda geçmemeleri gerekir.
`says_insufficient`	hayır	`{settles: [pattern, ...]}`: rapor, kanıtların yetersiz olduğunu söylemeli ve kendi yazdığı bir satırda meseleyi neyin netleştireceğini belirtmeli.
`no_action`	hayır	`{reason: [pattern, ...]}`: hiçbir şey yapılması gerekmeyen incident'lar için, örneğin yanlış alarm ya da bakım penceresi. Raporun nedeni belirtmesi gerekir.

DIAGNOSED olan bir bilinen neden, neyin teşhis edildiğini belirtmeli: bir class ya da cites veya cites_any altında dosyalar. Bunların hiçbirini içermeyen bir neden yine çalışır, ama her teşhis onunla eşleşir. Bu yüzden rapor o incident'ı yalnızca sonuca göre puanlanmış diye işaretler ve bunlardan kaç tane olduğunu sayar.

Dosyadaki bir hata, dosyanın adıyla birlikte bildirilir, örneğin known-cause.yaml: outcome must be one of .... O incident çalıştırılmadı olarak listelenir, diğerleri çalışmaya devam eder.

Cevabı Investigator'dan uzak tutmak

Investigator, repo'nun ilgili revizyondaki hâlini ve bundle/'ın bir kopyasını içeren bir klonda çalışır. Klonda başka hiçbir şey yoktur:

Klon git clone --no-local ile alınır, yani repo'nuzla hiçbir nesneyi paylaşmaz. origin'i kaldırılır ve .git içindeki hiçbir şey repo'nuzun yolunu içermez.
Revizyona kadarki geçmiş korunur, çünkü Investigator bundle'da geçen deploy'ları karşılaştırır. Revizyondan sonraki branch'ler ve tag'ler silinir, commit'leri de budanır. Çünkü sonraki bir commit, yani düzeltme, cevabın kendisidir.
Her incident kendi oturumunda (incident-pilot-<name>-...) ve uzun süreli bellek kapalıyken çalışır.

İki şeyi doğru yapmak size düşüyor: paketi repo'nun dışında tutun (ivralo repo'nun içindeki bir paketi kabul etmez, çünkü paketi takip eden bir revizyon bilinen nedenleri klona taşır) ve cevabı bundle'ın dışında tutun.

Repo'nuz yalnızca okunur. Ona hiçbir branch, worktree ya da dosya eklenmez ve klonlar iş bitince silinir.

Çalıştırma

ivralo pilot run ~/ivralo-pilot                         # içinde bulunduğunuz repo'ya karşı
ivralo pilot run ~/ivralo-pilot --repository ~/src/ledger
ivralo pilot run ~/ivralo-pilot --out ~/pilot-results   # rapor oraya gider
ivralo pilot run ~/ivralo-pilot --format json           # rapor tek bir JSON nesnesi olarak
ivralo pilot run ~/ivralo-pilot --fail-under 70         # %70'in altında eşleşmede çıkış 1

Bayrak	Anlamı
`--repository PATH`	Revizyonların bulunduğu repo. Varsayılan: çalışma alanı.
`--out PATH`	Raporun yazılacağı yer. Varsayılan: `<pack>/.pilot/<stamp>/`. Repo'nun dışında olmalı (`.ivralo/` dahil). Paketin içindeyse paketin en üst dizininde, adı noktayla başlayan bir klasör olmalı.
`--format text` ya da `json`	Text, raporun yolunu ve özet satırını yazar. JSON tüm raporu tek bir nesne olarak yazar.
`--hosted`	Makinenin dışında çalışan bir modelin kanıtları okumasına izin verir.
`--fail-under P`	0 ile 100 arasında bir eşik: incident'ların yüzde P'sinden azı eşleşirse çıkış kodu 1 olur.

Incident'lar sırayla çalışır. Her çalıştırmanın izi stderr'e yazılır, stdout'ta yalnızca sonuç olur.

Hosted modeller

ivralo incident için geçerli olan gizlilik kuralı burada da geçerli. Makinenin dışında çalışan bir model, siz --hosted vermedikçe kanıtları göremez. Hosted bir pilot maskeleme de ister: IVRALO_INCIDENT_MASK=true ve identifiers.json içinde size ait en az bir tanımlayıcı. Bunlar yoksa pilot başlamaz. Ayrıntılar Gizlilik ve maskeleme sayfasında.

Puanlar ve çıkış kodları

Her incident dört sonuçtan biriyle biter:

Durum	Anlamı
matched	Rapor, bilinen nedende belirtilen her konuda onunla örtüştü. Bilinen neden hiçbir sınıf ve dosya belirtmeyen bir `DIAGNOSED` ise matched (outcome only) olarak gösterilir. Bu durumda özet satırı `; N scored on outcome only` ile biter.
missed	Örtüşmedi. Nedeni de yazılır, örneğin `outcome DIAGNOSED, expected NOT_CODE_ISSUE` ya da `the report does not cite src/svc/parsing.py`.
no report	Investigator, ikinci ve son bir kez istendikten sonra bile rapor yazmadı. Nedeni yazılır.
not run	Incident'ın klasörü eksikti, revizyonu repo'da yok ya da çalıştırma başlamadan hata verdi.

Çıkış	Anlamı
`0`	Rapor yazıldı. Incident'ların sonucu ne olursa olsun.
`1`	Rapor yazıldı ama eşleşme oranı `--fail-under`'ın altında kaldı. Bu stderr'e yazılır.
`2`	Pilot başlayamadı. Sebebi repo, paket, format, repo'nun içini gösteren bir `--out`, 0 ile 100 dışında bir eşik ya da `--hosted` ve maskeleme olmadan kullanılan hosted bir model olabilir.

--fail-under kullanıldığında her incident hesaba katılır: çalıştırılmamış bir incident eşiğin aleyhine, yalnızca sonuca göre puanlanmış bir incident lehine sayılır. Bir geçişe güvenmeden önce bunlara bakın.

Pilot raporu

pilot.md ve pilot.json her incident için durumu, bilinen nedeni ve Investigator'ın bulduğu nedeni yan yana gösterir. Her incident'ın kendi report.md, report.json ve digest dosyaları da bunların yanına, <name>/ klasörüne kopyalanır.

Rapor bütün bilinen nedenleri içerdiği için iki dosyayı da yalnızca siz okuyabilirsiniz (Linux ve macOS'ta mod 0600, Windows'ta yalnızca sahibine açık bir ACL). Siz göndermedikçe rapordaki hiçbir şey makineden çıkmaz.