Dokümantasyon / Incident'lar

Alarm alımı

Alertmanager ve PagerDuty, ivralo'ya alarm gönderebilir. Tetiklenen her alarmdan küçük bir kanıt bundle'ı ve tek bir inceleme job'u çıkar. Aynı alarm tekrar gelirse ikinci bir inceleme başlamaz.

Nasıl çalışır

ivralo serve, servisin repo'sunda yerel API'yi çalıştırır. Alarmları bu API'nin iki route'u alır:

Route	Ne alır
`POST /alerts/alertmanager`	Prometheus Alertmanager'ın webhook'u, sürüm 4, Alertmanager nasıl gönderiyorsa öyle.
`POST /alerts/pagerduty`	PagerDuty'nin V3 webhook'u.

Gelen her teslimattaki tetiklenmiş her alarm için ivralo şunları yapar:

alerts/<source>-<fingerprint>-<time>/alert.md adında bir stub bundle yazar. İçinde alarmın adı, durumu, başlangıç ve bitiş zamanı, label'ları, annotation'ları ve link'leri bulunur (stub'da neler var);
bu bundle için kendi oturumunda tek bir inceleme job'u açar;
hemen cevap döner ve job'ları bu serve sürecinde sırayla çalıştırır.

Job, ivralo incident ile aynı dar ekiple çalışır: tek başına Investigator ve isteği ona devretmekten başka bir şey yapamayan bir lider. Rapor, ivralo incident'ın raporlarıyla aynı yere, .ivralo/incidents/ altına yazılır. Job'u ivralo jobs ve GET /jobs/<id> ile görebilirsiniz. Ayrıntılar Job'lar sayfasında.

Hiçbir şey indirilmez. Runbook URL'si, generator URL'si ya da incident sayfası stub'a düz metin olarak yazılır.

Sunucuyu başlatma

ivralo serve

Sunucu yalnızca 127.0.0.1:61017 adresini dinler (portu --port ya da IVRALO_API_PORT ile değiştirebilirsiniz) ve Ctrl+C ya da SIGTERM gelene kadar ön planda çalışır. Servis olarak kurulmaz. Sürekli ayakta kalsın istiyorsanız kendi servis yöneticinizle çalıştırın. GET /version dışındaki her route iki header ister:

Authorization: Bearer <token>. Token <home>/api-token dosyasındadır; onu ivralo init --token ya da ilk serve oluşturur;
X-Ivralo-Api-Version: 2.

Alertmanager

http_config'i bu ikisini de gönderen bir receiver ekleyin. Alertmanager token'ı dosyadan okur, böylece token config'te hiç görünmez:

receivers:
  - name: ivralo
    webhook_configs:
      - url: http://127.0.0.1:61017/alerts/alertmanager
        max_alerts: 100
        http_config:
          authorization:
            type: Bearer
            credentials_file: /home/ops/ivralo/api-token
          http_headers:
            X-Ivralo-Api-Version:
              values: ["2"]

max_alerts, gruplanmış bir teslimatın ivralo'nun sınırlarını aşmamasını sağlar (aşağıya bakın). API yalnızca loopback'ten gelen isteklere cevap verdiği için Alertmanager aynı makinede çalışmalı. Token dosyasını da Alertmanager'ı çalıştıran kullanıcının okuyabilmesi gerekir.

Bir alarm fingerprint'inden tanınır. 0.19'dan eski Alertmanager sürümleri fingerprint göndermez. Böyle bir body gelirse fingerprint, alarmın sıralanmış label'larından hesaplanır.

PagerDuty

PagerDuty bir loopback adresine erişemez. Bu yüzden aynı makinede küçük bir relay çalıştırın. Relay, PagerDuty'nin webhook'unu alsın, imzasını doğrulasın ve body'yi token ve sürüm header'ıyla birlikte http://127.0.0.1:61017/alerts/pagerduty adresine iletsin. ivralo PagerDuty imzasını kendisi doğrulamaz, bu iş relay'e düşer.

İnceleme yalnızca incident.triggered ve incident.reopened ile başlar. Bir PagerDuty incident'ı id'sinden tanınır. PagerDuty'nin pagey.ping test event'ine alarm olmadan 200 döner.

Cevap

Cevap hemen, tek bir JSON nesnesi olarak gelir:

{"source": "alertmanager", "alerts": [
  {"key": "alertmanager:5a1f0c3e9b2d7e44", "name": "CheckoutErrorRate", "status": "firing",
   "outcome": "started", "job": "3fa2c91b",
   "bundle": "alerts/alertmanager-5a1f0c3e9b2d7e44-20261023T094315Z-7c/"}]}

Her alarmın outcome'u started, duplicate (bu durumda alarmı zaten karşılayan job'un adı da verilir) ya da not_firing olur.

Durum	Ne zaman
`202`	Bu sunucuya çalıştırması için bir job verildi.
`200`	Hiç job verilmedi: alarmların hepsi ya çözülmüştü, ya tetiklenmemişti ya da zaten çalışan veya bitmiş bir job'un tekrarıydı.
`401`	Token yok ya da yanlış.
`403`	İstek loopback'ten gelmiyor ya da `Host` header'ı `127.0.0.1`, `localhost` veya `[::1]` değil.
`409`	Sürüm header'ı yok ya da yanlış, çalışma alanı bir git repo'su değil ya da hosted bir model kanıtları izin ve maskeleme olmadan okuyacaktı. Hiçbir şey yazılmaz.
`413`	Body 1 MiB'tan büyük. Bu, `Content-Length`'ten ya da parça parça gelirken anlaşılır.
`422`	Body JSON değil, bozuk ya da bir sınırı aşıyor. Hata mesajında ilgili alanın adı geçer.
`503`	Veritabanına bağlanılamadı.

Sınırlar

Sınır	Değer
Body	1 MiB
Teslimat başına alarm	100
Alarm başına label ve annotation	her biri için 100
Bir label ya da annotation adı	256 karakter
Bir değer: label, annotation, başlık, URL	8192 karakter
Bir fingerprint ya da incident id'si	128 karakter

Aynı alarm iki kez gelirse

Bir alarmın anahtarı, kaynağı ile fingerprint'inin birleşimidir, örneğin alertmanager:5a1f0c3e9b2d7e44. Bir job bu anahtarı şu durumlarda karşılar:

bitmediği sürece, ne kadar eski olursa olsun;
ve açıldıktan sonraki IVRALO_ALERT_DEDUP_SECONDS süresi boyunca (varsayılan 21600, yani altı saat).

Böyle bir job varken aynı alarm tekrar gelirse duplicate cevabı döner ve hiçbir şey başlamaz. Alertmanager'ın tekrarları da, art arda gelen teslimatlar da tek bir inceleme olarak kalır. Aynı anda gelen iki teslimat bir veritabanı kilidi altında kontrol edilir, onlardan da tek bir job çıkar.

Tekrar gelen alarmın job'u hâlâ queued durumdaysa, yani serve o job'a sıra gelmeden durdurulduysa, job bu sunucuya çalıştırılmak üzere verilir ve 202 döner. Yani yeniden başlatmada hiçbir alarm kaybolmaz. Çalışan, bir soruya cevap bekleyen ya da bitmiş bir job'a dokunulmaz. Durdurulmuş bir çalıştırmaya ivralo resume <id> ile devam edebilirsiniz.

Diskteki stub'lar

Stub'lar da her bundle gibi repo'nun working tree'sindeki dosyalardır. git status'ta görünmemeleri için klasörü .gitignore'a ekleyin:

alerts/

Stub'lar birikmez. Bir çalışma alanı en yeni IVRALO_ALERT_STUBS_KEEP stub'ı saklar (varsayılan 200; 0 hepsini saklar). Yeni bir stub yazılınca bu sayının dışında kalan en eskisi silinir. Ama bitmemiş bir job'un hâlâ okuduğu stub, sizin içine dosya eklediğiniz stub ve alerts/ altında alarm alımının oluşturmadığı klasörler hiçbir zaman silinmez.

Bir alarmı daha fazla kanıtla yeniden incelemek isterseniz log'ları stub'ın klasörüne kopyalayıp ivralo incident alerts/<stub>/ komutunu çalıştırın.