> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/observability/slos-audits.md). # SLO ve audit Service-level objective, gözlemlenen gateway trafiğinin erişilebilirlik veya gecikme hedefini karşılayıp karşılamadığını gösterir. Audit kaydı ise yönetim durumunu kimin değiştirdiğini ve neyin değiştiğini gösterir. Bunlar bağımsız sorgu ve saklama sözleşmelerine sahip ayrı ürün kayıtlarıdır. ## SLO izinleri ve tenant kapsamı SLO endpoint'leri standart admin rolü ve Admin API scope kurallarını kullanır: * Okuma çağrıları okunabilir admin rolü veya `admin:read` token scope'u gerektirir. * `POST`, `PUT` ve `DELETE` için admin writer veya `admin:write` gerekir. * Normal admin yalnızca kendi tenant'ıyla sınırlıdır. * Tenant atanmamış super admin `tenant_id` değerini açıkça vermelidir. Örneklerde şu değişkenler kullanılır: ```bash export KANGAL_URL='https://kangal.example.com' export KANGAL_TOKEN='kangaladm_...' export TENANT_ID='tenant-acme' ``` ## SLO nesnesi İki objective türü vardır: * `availability`: `500..599` yanıtı kötü olaydır. İstemci kaynaklı 4xx yanıtları bu error budget'ı tüketmez. * `latency`: Gecikmesi `latency_threshold_ms` değerinden büyük olan olay kötüdür. Availability hedefi oluşturma: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/slos" \ -d '{ "tenant_id": "tenant-acme", "gateway_id": "gw-production", "name": "Production availability", "description": "28 günlük başarılı gateway yanıtları", "objective": { "type": "availability", "target_percent": 99.9 }, "evaluation_window_minutes": 40320, "alert_policy": { "enabled": true, "warning_burn_rate": 1.0, "critical_burn_rate": 2.0 }, "enabled": true }' | jq ``` Latency hedefi oluşturma: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/slos" \ -d '{ "tenant_id": "tenant-acme", "gateway_id": "gw-production", "name": "Orders latency", "objective": { "type": "latency", "target_percent": 99.0, "latency_threshold_ms": 750 }, "evaluation_window_minutes": 10080, "alert_policy": { "enabled": true, "warning_burn_rate": 1.0, "critical_burn_rate": 3.0 } }' | jq ``` Doğrulama sınırları: | Alan | Kısıt | | --------------------------------- | -------------------------------------------------------------------- | | `name` | 1..120 karakter | | `description` | En fazla 500 karakter | | `gateway_id` | En fazla 128 karakter | | `objective.target_percent` | 0'dan büyük, 100'den küçük | | `objective.latency_threshold_ms` | Latency hedefinde zorunlu ve 0'dan büyük; availability için geçersiz | | `evaluation_window_minutes` | 5..43.200; varsayılan 10.080 (7 gün) | | `alert_policy.warning_burn_rate` | 0'dan büyük; varsayılan 1 | | `alert_policy.critical_burn_rate` | Warning değerinden büyük; varsayılan 2 | ## SLO endpoint'leri | Method ve path | Amaç | | --------------------------------------------------------------- | ----------------------------------------------------- | | `GET /api/v1/admin/slos?tenant_id=...&gateway_id=...` | SLO tanımlarını listele. | | `POST /api/v1/admin/slos` | SLO oluştur. | | `GET /api/v1/admin/slos/{slo_id}?tenant_id=...` | Tek SLO getir. | | `PATCH /api/v1/admin/slos/{slo_id}?tenant_id=...` | Seçilen SLO alanlarını güncelle. | | `DELETE /api/v1/admin/slos/{slo_id}?tenant_id=...` | SLO sil. | | `POST /api/v1/admin/slos/evaluate?tenant_id=...&gateway_id=...` | Eşleşen tüm SLO'ları şimdi değerlendir. | | `POST /api/v1/admin/slos/{slo_id}/evaluate?tenant_id=...` | Tek SLO'yu şimdi değerlendir. | | `POST /api/v1/admin/slos/{slo_id}/acknowledge` | İlgili SLO'nun warning veya critical alarmını onayla. | | `GET /api/v1/admin/slos/{slo_id}/timeline?tenant_id=...` | İlgili SLO'nun timeline olaylarını oku. | Update ve evaluation filtrelerinin tam request şeması için üretilen OpenAPI belgesini kullanın: ```bash curl -fsS "$KANGAL_URL/openapi.json" \ | jq '.paths | with_entries(select(.key | startswith("/api/v1/admin/slos")))' ``` ## Değerlendirme modeli Hesaplama: ``` allowed_bad_events = total_events * (100 - target_percent) / 100 burn_rate = bad_events / allowed_bad_events ``` Burn rate kritik eşiğe eşit veya büyükse durum `critical`, warning eşiğine eşit veya büyükse `warning`, diğer durumda `healthy` olur. Kullanılabilir örnek yoksa `no_data` döner. Objective veya alarm devre dışıysa veri varken healthy değerlendirilir; `no_data` otomatik olarak healthy'ye dönüşmez. Değerlendirme, istenen tenant, gateway ve pencere için mevcut saklanmış gözlemleri kullanır. Sonuç; kaynağı, örnek sayılarını, gözlemlenen zaman aralığını ve `evaluated_at` değerini bildirir. Tazelik ve kapsamı değerlendirirken bu alanları kullanın. Gözlemler gecikmeli gelebilir ve yapılandırılmış saklama süresi istenen pencerenin tamamını kapsamayabilir. Kullanılabilir örnek yoksa durum `no_data` olur. SLO sonucu tanılama amaçlı bir alarm sinyalidir; kesin faturalandırma kaydı, uyumluluk arşivi veya bütün isteklerin eksiksiz yakalandığının kanıtı değildir. Sonuca göre işlem yapmadan önce gözlemlenen zaman aralığının ve örnek sayısının hedefe uygun olduğunu doğrulayın. Değerlendirme, operatör, console veya harici scheduler evaluate endpoint'ini çağırdığında çalışır. Alarm durumunu otomatik yenilemek için toplu işlemi schedule edin: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/slos/evaluate?tenant_id=$TENANT_ID&gateway_id=gw-production" \ | jq ``` Alarm hedefi için yeterince kısa, ancak trafik/persistence yeni ve anlamlı örnek üretemeyecek kadar sık olmayan bir aralık seçin. ## Alarm durumu, acknowledgement ve timeline Yalnızca `warning` ve `critical` incident'lar acknowledge edilebilir. State transition acknowledgement'ı sıfırlar; böylece yeni koşul görünür olur. Timeline, SLO oluşturma/güncelleme, alarm geçişi ve acknowledgement olaylarını içerir. ```bash curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/slos?tenant_id=$TENANT_ID&gateway_id=gw-production" \ | jq '.items[] | {id, name, evaluation, alert}' curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/slos/SLO_ID/acknowledge" \ -d '{"tenant_id":"tenant-acme","note":"INC-8472 kapsamında inceleniyor"}' \ | jq curl -fsS -G \ -H "Authorization: Bearer $KANGAL_TOKEN" \ --data-urlencode "tenant_id=$TENANT_ID" \ --data-urlencode 'limit=100' \ "$KANGAL_URL/api/v1/admin/slos/SLO_ID/timeline" | jq ``` Timeline `limit` varsayılanı 100, üst sınırı 500'dür. ## Audit kayıtları Kangal'ın audit politikasının kapsadığı yönetim yazma işlemleri değiştirilemez audit kayıtları oluşturur. Kayıt şunları içerebilir: * Actor ID/kullanıcı adı, action, entity type ve entity ID. * Tenant ID, request ID, kaynak IP, timestamp ve metadata. * Değiştirilen durumun önceki ve sonraki değerleri. * Şema sürümü, `immutable: true`, önceki hash ve audit hash. Hash'ler tenant başına zincir oluşturur; global işlemlerin ayrı zinciri vardır. Kayıtları kurumun korumalı kanıt deposuna aktarın ve retention ile bütünlük doğrulamasını uyumluluk prosedürüne göre yürütün. Audit liste route'u kullanıcı/session access JWT'si gerektirir. Login ile alın: ```bash ACCESS_TOKEN=$( curl -fsS -X POST \ -H 'Content-Type: application/json' \ "$KANGAL_URL/auth/login" \ -d '{"username":"admin@example.com","password":"REDACTED","tenant_id":"tenant-acme"}' \ | jq -r '.access_token' ) curl -fsS -G \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data-urlencode "tenant_id=$TENANT_ID" \ --data-urlencode 'actions=create' \ --data-urlencode 'actions=update' \ --data-urlencode 'entity=service' \ --data-urlencode 'skip=0' \ --data-urlencode 'limit=50' \ --data-urlencode 'sort_direction=desc' \ "$KANGAL_URL/api/v1/admin/audits/" \ -D /tmp/kangal-audit-headers.txt | jq grep -i '^x-total-count:' /tmp/kangal-audit-headers.txt ``` `skip` varsayılanı 0'dır. `limit` varsayılanı 50, üst sınırı 200'dür. `sort_direction`, `asc` veya `desc` kabul eder; birden fazla action için `actions` parametresini tekrarlayın. Normal admin'in sorgusu kendi tenant'ına zorlanır; super admin global sorgu yapabilir veya tenant filtreleyebilir. Audit kapsamı yönetim değişikliklerine odaklanır; her read işleminin kaydı değildir. SLO durum değişikliklerinin ayrı incident timeline'ı, yapılandırmaların ayrı snapshot kayıtları vardır. Audit olayının olmamasını işlemin hiç gerçekleşmediğinin kanıtı saymayın. Audit storage lifecycle, yedek, export ve legal-hold politikasını veritabanı/platform katmanında belirleyin. ## Sorun giderme | Belirti | Kontrol edilecekler | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | SLO sürekli `no_data` | Tenant/gateway kimliklerini, gözlemlenen zaman aralığını, örnek sayılarını, gözlemlenebilirlik saklama süresini, veri alım sağlığını ve düşen yazma metriğini inceleyin. | | Availability SLO 4xx'i saymıyor | Beklenen davranış; yalnızca 5xx kötü availability olayıdır. | | Eşiğe eşit latency iyi sayılıyor | Beklenen davranış; kötü latency eşikten büyüktür. | | Acknowledgement başarısız | Yalnızca warning/critical durumlar onaylanır; state transition olmuş olabileceği için incident'ı yenileyin. | | Alarmlar yenilenmiyor | `POST /api/v1/admin/slos/evaluate` çağrısını çalıştırın veya zamanlayın; değerlendirme açık çağrılarla gerçekleşir. | | Admin API token ile audit `401` dönüyor | Audit route'u için `/auth/login` üzerinden kullanıcı access JWT'si alın. | | Audit listesi eksik görünüyor | `X-Total-Count` okuyun; `skip`/`limit` ile sayfalayın, istek başına en fazla 200 kayıt alınabilir. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/observability/slos-audits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.