Sorun Giderme

Knowentra'da kullanıcıya “agent cevap vermiyor” gibi görünen bir sorun; kimlik, retrieval, model endpoint'i, LLM Secure Gateway, workflow motoru, connector veya gerçek zamanlı bildirim katmanından kaynaklanabilir. En hızlı yöntem bütün servisleri yeniden başlatmak değil, arızanın kapsamını ve son başarılı sınırı bulmaktır.

Bu rehber şu teşhis döngüsünü kullanır:

Belirtiyi kaydet → Kapsamı daralt → Son değişikliği bul
                → Katmanları sırayla doğrula → Güvenli azaltım
                → Kök neden → Düzeltme ve önleme

Önce olay mı, destek talebi mi?

Güvenlik veya dış sistem etkisi şüphesinde teşhisten önce zararı sınırlandırın:

• İlgili agent, workflow veya trigger'ı durdurun.
• Credential'ı gerekiyorsa iptal edin.
• Queue ve retry'ların yeni etki üretmesini engelleyin.
• Audit ve trace kanıtını koruyun.
• Dış sistemde gerçek etkinin oluşup oluşmadığını kontrol edin.

İlk 10 dakika

1. Belirtiyi kesinleştirin

Şunları kaydedin:

İlk görülen zaman ve saat dilimi:
Etkilenen kullanıcı/organizasyon/Space:
Sayfa veya işlem:
Beklenen sonuç:
Gerçek sonuç ve görünen hata:
Support/request/trace/execution ID:
Tekrarlanabiliyor mu:
Son başarılı zaman:
Son değişiklik/release:

“Çalışmıyor” yerine “İK Space'indeki kullanıcılar 10:42 UTC'den beri kaynaklı cevap alamıyor; kaynaksız chat çalışıyor” gibi bir belirti arızayı hızlı daraltır.

2. Kapsamı bulun

3. Son değişikliği kontrol edin

• Platform veya workflow motoru release'i
• Migration
• Model alias/revision
• Gateway/guardrail politikası
• Connector scope/credential
• Agent prompt, bilgi veya araç
• Workflow sürümü, trigger veya credential
• DNS, sertifika, proxy veya firewall
• IdP grup/claim mapping

Zaman korelasyonu kök neden kanıtı değildir; fakat en güçlü ilk ipucudur.

4. Read-only sağlık kontrolü

Önce durumu değiştirmeyen kontroller:

• Servis health/readiness
• Son başarılı deployment ve migration revision
• DB/queue/model/connector dashboard'ları
• Disk, memory, connection pool ve certificate
• Son başarılı backup
• Error rate ve trace

Sorunu anlamadan queue temizleme, full reindex, migration downgrade veya volume silme uygulamayın.

Kanıt paketi

Destek veya incident kaydı için güvenli paket:

• Zaman aralığı ve saat dilimi
• Ortam ve release manifest kimliği
• Request/trace/workflow execution ID
• Redacted hata kodu ve kısa mesaj
• Etkilenen scope'un kimlikleri
• Son başarılı işlem zamanı
• İlgili servis sağlık durumu
• Secret içermeyen konfigürasyon diff'i
• Uygulanan geçici azaltım

Paylaşmadan önce temizleyin

Authorization: Bearer [REDACTED]
Cookie: [REDACTED]
api_key: [REDACTED]
email: user-42 / hash
prompt: [CONTENT OMITTED]
document: source_id + revision only
credential: credential_reference_id only

Katman sırası

Sorunu aşağıdan yukarı doğrulayın:

1. DNS / ağ / TLS
2. Veritabanı / obje / vektör / Redis
3. Uygulama ve migration
4. Kimlik ve yetki
5. Model / gateway / guardrail
6. Knowledge / retrieval
7. Tool / connector
8. Workflow / realtime / AI Feed
9. Tarayıcı ve kullanıcı deneyimi

Her katmanda “son başarılı sınır” bulunur. Örneğin model endpoint'ine gateway üzerinden sağlık çağrısı gidiyor ama gerçek prompt politika aşamasında engelleniyorsa ağ katmanını tekrar incelemek gerekmez.

Uygulama açılmıyor

Belirtiler

• Reverse proxy 502/503
• Healthcheck başarısız
• Uygulama restart loop
• Boş sayfa veya statik asset hatası

Kontrol sırası

1. DNS ve TLS sertifikasının doğru host'a çözüldüğünü doğrulayın.
2. Reverse proxy'nin upstream servis adı/portuna erişimini kontrol edin.
3. Uygulama process/container durumunu ve son exit code'u inceleyin.
4. Startup logunda eksik secret, DB bağlantısı veya migration hatası arayın.
5. Disk doluluğu, inode, memory/OOM ve file permission kontrol edin.
6. Uygulama image digest'inin onaylı release manifest'iyle eşleştiğini doğrulayın.
7. Readiness ile liveness farkını inceleyin; bağımlılık hazır olmadan trafik açılmasın.

Güvenli azaltım

Yeni release sonrası başladıysa ve şema uyumluysa önceki onaylı uygulama image'ına dönüş değerlendirilebilir. Migration geri çevrilemezse kör rollback yerine roll-forward veya restore planını kullanın.

Veritabanı sorunları

Belirtiler

• Yüksek 5xx
• Login ve tüm yazmalar yavaş
• Connection timeout
• Migration tamamlanmıyor
• Deadlock veya lock bekleme

Kontroller

• DB process/cluster sağlığı ve replication lag
• Disk ve transaction log kapasitesi
• Connection pool kullanım/doygunluk
• Uzun sorgular, lock sahibi ve bekleyen transaction
• Son migration ve uygulama şema uyumu
• Network latency ve TLS
• Backup/PITR zinciri

Connection limitini körlemesine artırmak sorunu büyütebilir. Uygulama instance × pool size + worker/migration/admin bağlantılarının toplamını hesaplayın.

Migration lock oluşturuyorsa işlemi hemen öldürmeden önce transaction durumunu ve rollback maliyetini değerlendirin. Değişiklik kaydı ve DB sahibiyle hareket edin.

SSO veya giriş çalışmıyor

Tüm kullanıcılar

1. IdP discovery/JWKS endpoint erişimini kontrol edin.
2. Issuer, audience, client ID ve secret revision'ını doğrulayın.
3. Redirect URI ve reverse proxy scheme/host değerini karşılaştırın.
4. Sertifika ve saat kaymasını kontrol edin.
5. IdP olay/limit durumunu inceleyin.
6. Logout/back-channel değişikliğinin session'ı bozup bozmadığını test edin.

Tek kullanıcı

• Hesap aktif mi ve doğru issuer+subject ile eşleşiyor mu?
• SCIM pasifleştirme veya duplicate account var mı?
• Organizasyon/departman/Space üyeliği aktif mi?
• Group claim boyutu veya mapping çakışması var mı?
• Eski session/role cache iptal edilmiş mi?

Hata matrisi

Break-glass yalnız IdP arızasında kontrollü yönetim için kullanılmalı; normal kullanıcıları tenant kontrolünü atlayan yerel hesaplara taşımayın.

Kullanıcı başka Space'i göremiyor veya fazla veri görüyor

Erişim eksik

1. Organizasyon üyeliğini doğrulayın.
2. Departman üyeliği ve aktiflik durumuna bakın.
3. Space üyeliği/rolü veya join-request sonucunu kontrol edin.
4. Kaynağın gerçekten o Space/departmana bağlı olduğunu doğrulayın.
5. Session ve permission cache'in rol değişimini aldığını kontrol edin.
6. Backend yetki kararını audit event'inden inceleyin.

Fazla erişim

Bu güvenlik olayı olabilir:

1. İlgili Space/agent/connector'ı erişime kapatın.
2. Kullanıcının istemci tarafından gönderdiği scope ID ile sunucu scope'unu karşılaştırın.
3. Retrieval filtreleri ve access grant'ları inceleyin.
4. Shared/discoverable ile member erişiminin karışmadığını doğrulayın.
5. Connector ACL revision ve son permission sync'i kontrol edin.
6. Olası veri erişimini audit'ten belirleyin.

UI düğmesinin gizli olması yetki kanıtı değildir; backend endpoint'ini negatif test edin.

Model listede görünmüyor

• Provider/model konfigürasyonu etkin mi?
• Kullanıcının organizasyon ve Space modeli kullanma izni var mı?
• Model allowlist ve policy mapping doğru mu?
• Yerel model runtime model artefact'ını gerçekten yükledi mi?
• Provider catalog çağrısı timeout/rate limit alıyor mu?
• Yeni model alias'ı agent'ın sabit ID'siyle uyuşuyor mu?
• Cache eski katalog sonucunu tutuyor mu?

Modeli görünür yapmak için global allowlist'i genişletmeden önce dar test kullanıcı/Space ile doğrulayın.

Chat yanıt vermiyor veya çok yavaş

Ayrıştırma

Kontroller

• Model endpoint health, queue ve inference süresi
• Gateway ve guardrail latency/timeout
• Provider 429, quota veya auth
• Context boyutu ve truncation
• Retrieval ve tool çağrısı süreleri
• Proxy timeout ve response buffering
• GPU memory/CPU saturation
• Model fallback'in policy nedeniyle reddedilmesi

Timeout'u artırmadan önce zamanın hangi span'de harcandığını bulun. Uzun timeout, kullanıcı bekleyişini ve worker doygunluğunu artırabilir.

LLM Secure Gateway hataları

Harici model çağrısı hiç gitmiyor

• Gateway health ve uygulamadan ağ/TLS erişimi
• Organizasyon/departman policy çözümü
• Model hedefinin izinli olması
• İstek boyutu ve desteklenen format
• Gateway timeout ve upstream auth

Gateway kullanılması gereken bir akışta erişilemiyorsa güvenli davranış harici çağrıyı engellemektir. Gateway'i atlayan doğrudan provider yolu açmayın.

Maskeleme fazla veya eksik

1. Kullanılan policy revision'ı kayıttan bulun.
2. Organizasyon temel ve departman sıkılaştırmasını ayrı inceleyin.
3. Dil, entity türü ve threshold'u kontrollü örnekle test edin.
4. Girdinin gateway'den önce normalize edilip bozulmadığını kontrol edin.
5. Restore mapping süresi ve request bağlamını doğrulayın.
6. Tam hassas girdiyi loglamadan sentetik test kullanın.

Belgeler yükleniyor ama agent bilmiyor

Bir dosyanın “yüklendi” görünmesi indekslendiği anlamına gelmez:

uploaded → parsed → chunked → embedded → indexed → authorized retrieval

Kontrol sırası

1. Dosya ilgili bilgi tabanına gerçekten bağlı mı?
2. Parse/embedding işi tamamlandı mı, karantinada mı?
3. Aktif index revision doğru mu?
4. Agent'ın yayınlanan sürümünde bilgi tabanı atanmış mı?
5. Kullanıcı Space ve belge erişimine sahip mi?
6. Sorgu retrieval sonucu chunk döndürüyor mu?
7. Context modele taşınmış mı?
8. Citation source revision doğru mu?

Belirtiler

Doğrudan full reindex başlatmadan tek belgeyi source ID ve revision boyunca izleyin.

Yanıt yanlış veya kaynak desteklemiyor

1. Kullanıcının tam iddiasını ve gösterilen citation'ı kaydedin.
2. Citation'daki source revision'ın o an aktif olduğunu doğrulayın.
3. Retrieval'a gelen chunk'ları ve skorları inceleyin.
4. Çelişen/eski kaynak olup olmadığını kontrol edin.
5. Context'e hangi chunk'ların girdiğini bulun.
6. Agent system talimatındaki kaynak yokluğu davranışını test edin.
7. Aynı evaluation örneğini sabit model/agent/index revision ile tekrar çalıştırın.

Yanlış cevabı yalnız prompt'u uzatarak düzeltmeyin. Sorun kaynağın güncelliği, chunking, retrieval, context selection veya citation katmanındaysa doğru katmanı düzeltin.

Connector senkronize etmiyor

401/403

• Token expiry, consent ve credential revision
• Tenant/audience/scope
• Kaynak yöneticisinin izin değişikliği
• Servis hesabının aktifliği

Credential'ı loglamayın; reference ID ve hash ile karşılaştırın.

429 veya yavaş sync

• Retry-After uyumu
• Worker concurrency ve sayfa boyutu
• Aynı credential'ı kullanan diğer işler
• Kaynak API kotası
• Backoff ve checkpoint davranışı

Sync başarılı, veri eksik

• Include/exclude filtresi ve root değişikliği
• Pagination/cursor'ın erken bitmesi
• Checkpoint'in türev yazımdan önce ilerlemesi
• Parser/embedding karantinası
• Ani source count düşüşü
• ACL nedeniyle retrieval'dan elenme

Toplu silme görünümü

Silme işini dondurun. Kimlik, scope, filtre revision, pagination ve kaynak health'i doğrulanmadan mevcut indeksi silmeyin. Örnek source ID'leri kaynaktan doğrudan kontrol edin.

Agent aracı görünmüyor

• Araç organizasyon kataloğunda mı?
• Departmana atanmış mı?
• Space'in izinli alt kümesinde mi?
• Agent'ın yayınlanan sürümüne ekli mi?
• Kullanıcının işlem izni var mı?
• Credential Space/workspace kapsamına bağlı mı?
• Tool schema provider/model tarafından destekleniyor mu?

Katalogda görünmek çalıştırma yetkisi değildir. Etkili izin bütün kesişimlerden geçmelidir.

Araç çağrısı hata veriyor

Timeout sonrası yazma işlemini hemen tekrar etmeyin. Business key veya downstream request ID ile etkinin oluşup oluşmadığını kontrol edin.

Workflow editörü açılmıyor

• Kullanıcı ilgili Space'in üyesi mi?
• Knowentra Space ile workflow workspace binding mevcut mu?
• Workflow servisi ve realtime endpoint'i erişilebilir mi?
• Trusted sign-in/session handoff başarılı mı?
• Proxy iframe/CSP/CORS ve cookie ayarları doğru mu?
• Kullanıcının workflow workspace permission'ı sync olmuş mu?
• Workflow metadata'sındaki motor kimliği mevcut mu?

Kullanıcıyı global workflow admin yaparak sorunu çözmeyin. Space üyeliği ile workspace grant eşlemesini düzeltin.

Workflow başlamıyor

Manuel çalışıyor, trigger çalışmıyor

• Schedule aktif, saat dilimi ve next-run doğru mu?
• Webhook endpoint, signature ve event type doğru mu?
• API key/JWT audience ve scope geçerli mi?
• Poller checkpoint ve credential sağlıklı mı?
• Yayınlanan deployment version trigger'a bağlı mı?

Hiçbir şekilde çalışmıyor

• Workflow yayınlanmış/çalıştırılabilir sürümde mi?
• Grafik doğrulaması ve gerekli alanlar tamam mı?
• Credential referansları çözülebiliyor mu?
• Worker/queue sağlıklı mı?
• Workspace yetkisi doğru mu?
• Model, MCP veya integration dependency mevcut mu?

Workflow running durumda takıldı

1. Execution ve workflow version kimliğini sabitleyin.
2. Son başlayan/tamamlanan node'u trace'ten bulun.
3. Node timeout ve downstream request durumunu kontrol edin.
4. Queue lease/worker heartbeat ve retry sayısını inceleyin.
5. Human-in-the-loop pause durumuyla running'in karışmadığını doğrulayın.
6. Dış yazma olasılığı varsa business key ile kaynak sistemi kontrol edin.
7. İptal/yeniden çalıştırma kararını süreç sahibiyle verin.

Worker'ı yeniden başlatmak execution'ı tekrar koşturabilir. İdempotency ve lease semantiğini bilmeden toplu restart yapmayın.

Workflow onayda takıldı

• Motor tarafında paused execution/snapshot var mı?
• Knowentra tarafında pending approval kaydı var mı?
• İki kayıt execution/context ID ile eşleşiyor mu?
• Onay kartı doğru Space üyelerine görünür mü?
• Onaylayanın rolü hâlâ geçerli mi?
• Resume URL/context ve servis kimliği geçerli mi?
• Approval/paused snapshot süresi dolmuş mu?

“Reddet” davranışı kurulu sürümde açık reject dalı taşımıyorsa execution iptal edilmelidir. rejected girdisiyle resume etmek akışı sonraki yazma node'una taşıyabilir.

Workflow tamamlandı ama AI Feed kartı yok

Üç sınırı ayrı kontrol edin:

1. Workflow motoru: Execution terminal duruma geldi mi ve completion callback denendi mi?
2. Knowentra backend: Callback kimliği/purpose doğrulandı ve workflow→Space eşleşti mi?
3. UI/realtime: Kalıcı feed kaydı var mı, kullanıcı ilgili Space üyesi mi, socket bağlı mı?

Kalıcı kayıt var ama UI yenilenince görünüyorsa sorun realtime/socket katmanındadır. Kayıt yoksa bridge URL, servis secret/purpose, workflow binding veya migration incelenir.

Feed özeti şablon kaldıysa ana workflow başarısız sayılmaz. Notification modelinin kapalı, rate-limit'te veya geçici erişilemez olması degrade davranış olabilir.

Realtime güncellemeler görünmüyor

• Tarayıcı normal HTTP istekleri çalışıyor mu?
• Socket endpoint URL, scheme ve port doğru mu?
• Reverse proxy WebSocket upgrade header'larını geçiriyor mu?
• CORS/trusted origin ve cookie doğru mu?
• Realtime servis health ve DB/Redis bağlantısı var mı?
• Kullanıcı doğru department/Space room'una katılmış mı?
• Çoklu instance'ta ortak adapter/Redis yapılandırılmış mı?

UI yenilemesinde durum geliyorsa kalıcı veri sağlıklı, push kanalı bozuk olabilir. Geçici olarak polling kullanılabilir; yetki kontrollerini azaltmayın.

Performans sorunu

Önce gecikmeyi bölün

DNS/TLS
→ ingress
→ auth
→ retrieval
→ gateway/policy
→ model queue + inference
→ tool/workflow
→ response streaming

P50 tek başına yeterli değildir; P95/P99 ve queue bekleme süresini inceleyin.

Kaynak belirtileri

Instance sayısını artırmadan downstream limit, DB pool ve ortak state kapasitesini kontrol edin.

Disk doluyor

Kaynağı belirleyin:

• Veritabanı/WAL
• Obje yüklemeleri
• Vektör indeksleri
• Model artefact'ları
• Audit ve uygulama logları
• Geçici parse dosyaları
• Backup'ın yanlışlıkla aynı volume'a yazılması

Aktif dosyayı rastgele silmeyin. Retention/rotation, orphan cleanup ve model/index yaşam döngüsü üzerinden güvenli temizlik yapın. Önce backup ve geri dönüş ihtiyacını kontrol edin.

Migration sonrası hata

1. Çalışan uygulama digest'i ile schema revision'ı karşılaştırın.
2. Migration'ın tam mı kısmi mı olduğunu belirleyin.
3. Eski ve yeni instance'ın aynı anda çalışıp çalışmadığını kontrol edin.
4. Yeni constraint'i ihlal eden veri veya başarısız backfill'i bulun.
5. Migration log, lock ve transaction sonucunu koruyun.
6. Rollback/roll-forward kararını değişiklik planına göre verin.

Schema'yı elle “hızlıca düzeltmek” sonraki migration zincirini bozabilir. Acil manuel değişiklik zorunluysa exact SQL, onay, önce/sonra şema ve telafi migration'ını kaydedin.

Audit veya telemetry gelmiyor

• Audit seviyesi/include/exclude yolları
• Kalıcı audit dosyası/volume ve permission
• Disk doluluğu ve rotation
• OTEL traces/metrics/logs etkinliği
• OTLP endpoint/protocol/TLS/auth
• Collector queue ve dropped telemetry
• Network egress ve backend kapasitesi
• Sampling kararı

Audit ile telemetry kaybını ayırın. Trace sampling beklenen olabilir; kritik audit olayının kaybı değildir. Audit pipeline boşluğu güvenlik alarmı üretmelidir.

Sağlık kontrolü doğru ama kullanıcı işlemi bozuk

Basit health endpoint çoğu zaman yalnız process'in yaşadığını gösterir. Derin ama güvenli synthetic testler ekleyin:

• SSO/JWKS erişimi
• DB read/write test kaydı
• Obje yaz/oku/sil sentetik obje
• Vektör test koleksiyonu sorgusu
• Gateway sentetik maskeleme testi
• Test modeline kısa inference
• Sandbox connector read
• İdempotent test workflow
• Audit/OTLP teslimi

Sentetik test gerçek müşteri verisi veya üretim dış etkisi kullanmamalıdır.

Sık yapılan hatalar

Kök neden analizi

Incident kapatılmadan:

• Gerçek kök neden ve tetikleyen koşul
• Neden mevcut kontrol/test bunu yakalamadı?
• İlk algılama sinyali ve gecikmesi
• Etkilenen kullanıcı, veri ve dış işlemler
• Geçici azaltım ve kalıcı düzeltme
• Tekrarı önleyen test, alarm veya tasarım değişikliği
• Dokümantasyon/runbook güncellemesi
• Sahip ve son tarih

“İnsan hatası” kök neden değildir. Hangi koruma, görev ayrılığı, validation veya otomasyonun eksik olduğunu bulun.

Eskalasyon paketi

Sorunu başka ekibe devrederken:

Özet ve iş etkisi
Başlangıç zamanı / son başarılı zaman
Etkilenen kapsam
Release ve revision kimlikleri
Request/trace/execution ID
Yeniden üretim adımları
Beklenen / gerçek sonuç
Yapılan read-only kontroller
Uygulanan azaltım
İlgili redacted log/trace
Sorulan net soru

Yalnız yüzlerce satır log göndermek yerine zaman aralığı ve correlation kimliğiyle ilgili kısmı sunun.

Sorun giderme kontrol listesi

• Belirti, zaman, kapsam ve beklenen sonuç kesin.
• Güvenlik/dış etki riski varsa önce sınırlandırıldı.
• Son başarılı zaman ve son değişiklik bulundu.
• Request/trace/execution/business key kaydedildi.
• Read-only kontroller değişiklikten önce yapıldı.
• Katmanlar son başarılı sınır bulunarak elendi.
• Secret ve hassas içerik kanıt paketinden temizlendi.
• Retry öncesi dış etkinin oluşup oluşmadığı kontrol edildi.
• Tenant/Space sorunu backend negatif testiyle doğrulandı.
• RAG sorunu upload→index→retrieval zincirinde izole edildi.
• Connector'da checkpoint, scope ve hacim anomalisi incelendi.
• Workflow'da version, node, pause ve idempotency kontrol edildi.
• Realtime ile kalıcı backend durumu ayrıldı.
• Geçici azaltım güvenlik kontrolünü zayıflatmıyor.
• Kök neden, kalıcı düzeltme ve önleyici aksiyon sahipli.
• Runbook, test ve alarm güncellendi.

İlgili rehberler

• Sistem sınırları: Platform Mimarisi
• Üretim kontrolleri: Üretim Kurulumu Kontrol Listesi
• İzleme: Audit Logları ve Gözlemlenebilirlik
• Connector: Connector Yönetimi ve Senkronizasyon
• Workflow: Workflow Tasarım Rehberi
• Kurtarma: Yedekleme, Geri Yükleme ve Felaket Kurtarma