Audit Logları ve Gözlemlenebilirlik

Knowentra gibi agent ve workflow çalıştıran bir platformda “log tutuyoruz” yeterli değildir. Operasyon ekibi bir kesintinin nedenini, güvenlik ekibi bir yetki kararını, veri sahibi bir kaynağın kullanımını ve süreç sahibi dış sistemde oluşan etkiyi farklı kanıtlarla incelemek ister.

Bu rehber dört kayıt türünü birlikte ama ayrı amaçlarla tasarlar:

Audit ile log aynı şey değildir

Bir stack trace, kullanıcının neden yetkili kabul edildiğini göstermez. Bir audit kaydı da CPU doygunluğunu teşhis etmek için tasarlanmamalıdır.

Tek bir merkezi depoda tutulabilirler; fakat şema, erişim, saklama ve sorgu politikaları ayrı kalmalıdır.

Uçtan uca izleme zinciri

Bir kullanıcı sorusunu şu kayıtlarla ilişkilendirebilmelisiniz:

request_id / trace_id
  ├── kullanıcı + organizasyon + Space
  ├── session / auth kararı
  ├── agent_id + agent_version
  ├── retrieval_query_id
  │     └── source_id + source_revision + chunk_id
  ├── policy_decision_id
  │     └── maskeleme / engelleme sonucu
  ├── model_request_id
  │     └── provider + model + token + latency
  ├── tool_call_id
  │     └── operation + approval + external_record_id
  └── workflow_execution_id
        └── node spans + retry + final status

Bu zincir bütün prompt ve payload'ı her yere kopyalayarak kurulmaz. Ortak, anlamsız kimlikler ve güvenli metadata kullanılır.

Ortak correlation modeli

Kimlikler

Uzun workflow, başlatan HTTP isteği bittikten sonra devam eder. Bu nedenle başlangıç trace_id değerini execution metadata'sına bağlayın; her resume/retry için yeni teknik trace oluşsa da aynı workflow ve business key korunur.

Servisler arası aktarım

• W3C Trace Context veya altyapınızın standart trace header'larını kullanın.
• Dış kullanıcıdan gelen trace kimliğine körü körüne güvenmeyin; doğrulayın veya yenisini üretin.
• Queue/message header'larında trace ve business context taşıyın.
• Correlation kimliğini kullanıcıya destek referansı olarak gösterebilirsiniz.
• Kimliğe e-posta, tenant adı veya kişisel veri gömmeyin.

Audit olay şeması

Yapılandırılmış bir audit olayı en az şu alanları içermelidir:

{
  "event_id": "aud_...",
  "occurred_at": "2026-07-31T10:42:18.421Z",
  "event_type": "workflow.approval.resolved",
  "outcome": "success",
  "actor": {
    "type": "user",
    "id": "usr_...",
    "session_id_hash": "..."
  },
  "scope": {
    "organization_id": "org_...",
    "department_id": "dep_...",
    "space_id": "spc_..."
  },
  "target": {
    "type": "workflow_execution",
    "id": "run_..."
  },
  "action": "approve",
  "authorization": {
    "role": "department_admin",
    "decision": "allow",
    "policy_revision": "pol_17"
  },
  "correlation": {
    "trace_id": "...",
    "request_id": "...",
    "business_key": "EXP-2026-1842"
  },
  "change": {
    "before": "pending",
    "after": "approved"
  }
}

Şema ilkeleri

• Olay türlerini domain.resource.action biçiminde sürümlü tutun.
• UTC ve yüksek çözünürlüklü timestamp kullanın.
• Aktör ile teknik servisi ayırın.
• Başarısız/engellenmiş denemeleri de kaydedin.
• Önce/sonra değerinde secret veya tam hassas payload bulundurmayın.
• “Admin yaptı” yerine rol, kapsam ve yetki kararını kaydedin.
• Audit yazımı başarısızsa kritik işlemin davranışını risk sınıfına göre belirleyin.

Aktör türleri

Agent bir dış etki oluşturduğunda yalnız agent adını yazmayın. Başlatan kullanıcı, agent sürümü, çalıştıran servis ve onaylayan kişi ayrı alanlarda korunmalıdır.

Audit edilmesi gereken olaylar

Kimlik ve yetki

• Oturum açma başarı/başarısızlığı ve logout
• MFA/SSO/LDAP/SCIM yaşam döngüsü
• Oturum ve API anahtarı iptali
• Organizasyon, departman ve Space üyelik değişikliği
• Rol yükseltme/düşürme
• Break-glass ve platform admin kullanımı
• Yetki reddi ve çapraz-scope erişim denemesi

Agent ve model

• Agent oluşturma, değiştirme, yayınlama, geri alma ve kapatma
• Temel model veya sağlayıcı değişikliği
• Bilgi tabanı ve araç ataması
• Kullanıcı kapsamının genişletilmesi
• Model egress politika kararı
• Maskeleme, engelleme ve fallback sonucu
• Araç çağrısı ve dış sistem etkisi

Workflow

• Taslak ve yayınlanan sürüm değişikliği
• Trigger oluşturma ve secret rotasyonu
• Execution başlatma, duraklama, resume, iptal ve tamamlama
• Retry ve dead-letter taşıma
• İnsan onayı ve ret
• Credential referansı ve operation değişikliği
• Telafi/rollback işlemi

Knowledge ve connector

• Connector oluşturma, scope ve credential değişikliği
• Full/incremental sync başlangıç ve sonucu
• Büyük hacim anomalisi
• Belge/ACL ekleme, güncelleme ve silme
• Karantina ve toplu silme onayı
• Embedding/index revision geçişi
• Veri export ve retention silmesi

Yönetim

• Secret ve şifreleme anahtarı rotasyonu
• Audit/telemetry ayarı veya saklama değişikliği
• Backup/restore işlemi
• Sistem konfigürasyonu ve feature flag değişikliği
• Kullanıcı/veri export'u

Prompt ve yanıt loglama

Prompt, retrieval bağlamı ve model yanıtı teşhis için değerli; aynı zamanda yeni bir hassas veri kopyasıdır.

Dört seviye

Varsayılanı metadata-only seçin. Tam içerik gerekiyorsa amaç, süre, erişim, onay ve otomatik silme belirleyin.

Asla loglanmaması gerekenler

• Parola, session cookie ve bearer token
• API anahtarı, OAuth refresh token ve private key
• Maskelenmiş değeri geri açan eşleme
• Veritabanı connection string'i
• Tam authorization header
• Gereksiz dosya içeriği
• Model sağlayıcısına gönderilmeyen ama prompt hazırlığında bulunan hassas veri

RAG gözlemlenebilirliği

RAG için yalnız model cevabını izlemek sorunun nerede olduğunu göstermez:

Kullanıcı “yanlış cevap” bildirdiğinde şu ayrımı yapabilmelisiniz:

• Kaynak connector tarafından alınmamış mı?
• Belge ayrıştırma/chunk aşamasında bozulmuş mu?
• Yetki filtresi doğru kaynağı dışlamış mı?
• Retrieval yanlış chunk seçmiş mi?
• Doğru bağlama rağmen model yanlış mı üretmiş?
• Yanıt doğru ama citation yanlış mı eşleşmiş?

Ham belge içeriğini trace attribute'larına koymayın; source ve revision ID ile güvenli yetkili ekrana bağlayın.

LLM ve gateway metrikleri

• İstek ve hata sayısı: provider/model/outcome
• P50/P95/P99 first-token ve toplam gecikme
• Prompt/completion token
• Queue ve model inference süresi
• Timeout, rate limit ve fallback
• Maskeleme/engelleme karar sayısı
• Politika bulunamadı veya fail-closed sayısı
• Context limit ve truncation
• Tahmini maliyet veya yerel kapasite kullanımı

Metric label'ına user ID, prompt, belge ID veya yüksek kardinaliteli request ID koymayın. Bunlar log/trace alanıdır. Yüksek kardinalite metric backend maliyetini ve performansını bozar.

Agent araç çağrıları

Her araç çağrısında:

agent_id + version
initiating_user_id
tool_id + operation_id
argument_schema_version
authorization_decision
approval_id (varsa)
credential_reference_id (değer değil)
downstream_request_id
idempotency_key_hash
duration + outcome
external_record_id

Argümanların tamamını varsayılan loglamayın. Alıcı, tutar veya kayıt gibi kritik alanları veri sınıflandırmasına göre redacted veya hash'li kaydedin.

Workflow execution trace

Workflow trace'i node bazında şu bilgileri sağlamalıdır:

• Workflow ve yayınlanan sürüm
• Trigger/event kimliği
• Node/blok kimliği ve sürümü
• Başlangıç/bitiş, süre ve durum
• Retry sayısı ve önceki hata sınıfı
• Girdi/çıktı şema revision'ı
• AI node için model ve token
• Entegrasyon node'u için provider operation ve downstream request ID
• Pause/resume context ve onay referansı
• Child workflow ilişkisi
• Final durum ve telafi sonucu

Node input/output'u görüntüleyen ekranın erişimi Space üyeliği ve hassas veri politikasıyla sınırlandırılmalıdır. Execution loguna erişim, connector credential'ını görme yetkisi vermez.

Metrik tasarımı

RED

İstek servisleri için:

• Rate: Saniyedeki istek
• Errors: Hata/ret oranı
• Duration: Gecikme dağılımı

USE

Kaynaklar için:

• Utilization: CPU, GPU, bağlantı pool'u, worker kapasitesi
• Saturation: Queue depth, bekleyen connection, GPU memory
• Errors: Disk, OOM, exporter ve altyapı hataları

İş metrikleri

• Başarıyla tamamlanan workflow
• İnsan onayına giden ve reddedilen işlem
• Agent insan devralma oranı
• Connector freshness SLO uyumu
• Kaynaksız RAG yanıt oranı
• Tekrarlanan dış etki engelleme sayısı

İş metriği audit yerine geçmez; kişisel veri içermeyen toplu görünüm sağlar.

OpenTelemetry ve OTLP

Knowentra telemetry etkinleştirildiğinde trace ve metrikleri OTLP üzerinden kurumun collector'ına gönderebilir. Önerilen topoloji:

Knowentra servisleri ─┐
Workflow / realtime ──┼→ İç OTLP Collector
Gateway / worker ─────┘        ├→ Trace backend
                              ├→ Metric backend
                              └→ Log/SIEM

Collector:

• İnternete doğrudan açık olmamalı.
• TLS ve kimlik doğrulama kullanmalı.
• Tenant/environment/service attribute'larını eklemeli.
• Secret ve hassas attribute'ları filtrelemeli.
• Batch, queue ve retry ile backend kesintisini tamponlamalı.
• Kendi dropped span/metric ve exporter hatalarını izlemeli.

Telemetry backend kesildiğinde uygulamanın ana işlevi genellikle devam edebilir; ancak kritik audit olayları için aynı “best effort” yaklaşımı uygun olmayabilir.

Audit bütünlüğü

• Append-only veya immutable/WORM hedef kullanın.
• Audit yazan hesap ile okuyan/silen rolleri ayırın.
• Dosya kullanılıyorsa rotation sonrası merkezi güvenli hedefe taşıyın.
• Hash chain, imza veya obje lock gibi tamper-evidence kontrolleri değerlendirin.
• Saat kaynağını güvenilir NTP ile senkronize edin.
• Event ID ile duplicate ve gap kontrolü yapın.
• Export pipeline düşen/atlanmış olay sayısını izlesin.
• Audit konfigürasyonu değişikliği de audit edilsin.

Audit dosyasını yalnız container'ın geçici filesystem'inde tutmayın. Kalıcı volume veya merkezi collector kullanın ve disk doluluğunu alarm kapsamına alın.

Erişim ve görevlerin ayrılığı

Arama ve export işlemleri ayrıca audit edilmelidir. Denetçiye geniş üretim admin rolü vermek yerine salt-okunur, süreli erişim verin.

Saklama ve silme

Her kayıt türü için ayrı politika:

“Her şeyi sonsuza kadar sakla” güvenlik değildir. Erişim yüzeyini ve ihlal etkisini büyütür. Silme işlemi audit edilip legal hold ile çakışmadığı doğrulanmalıdır.

Sampling

• Metrikler genellikle sampling yapılmadan toplulaştırılır.
• Başarılı trace'ler head veya tail sampling ile azaltılabilir.
• Hata, yüksek gecikme, politika engeli ve kritik workflow trace'leri korunabilir.
• Audit olayları sampling'e tabi tutulmamalıdır.
• Prompt içeriği sampling'i ayrı veri politikası gerektirir.

Sampling kararının incident sırasında gereken trace'i kaybettirmediğini periyodik olarak test edin.

Dashboard seti

Platform sağlığı

• Web/API rate, error, latency
• DB pool, sorgu, lock ve disk
• Queue depth ve en yaşlı iş
• Model/gateway sağlık ve gecikme
• Redis/realtime bağlantıları
• OTLP exporter drop/error

AI kalitesi ve güvenliği

• Model ve agent sürümüne göre hata
• Kaynaksız RAG ve citation sorunu
• Policy mask/block ve fallback
• Tool authorization denial
• İnsan devralma ve geri bildirim

Workflow ve connector

• Execution outcome ve süre
• Paused/approval/dead-letter yaşı
• Retry ve idempotency conflict
• Connector checkpoint/freshness
• Parse/embed/index failure
• Pending delete ve reconciliation farkı

Dashboard her panelde environment ve organizasyon gibi güvenli filtreler sunmalı; kişisel veri ve sınırsız yüksek kardinalite taşımamalıdır.

Alarm tasarımı

İyi alarm belirli bir aksiyon ve sahip üretir:

Alarmda prompt veya hassas payload göstermeyin. Correlation ID ve yetkili inceleme bağlantısı verin.

Olay inceleme akışı

1. Kullanıcıdan zaman, görünen hata ve support/correlation ID alın.
2. Audit'ten aktör, kapsam ve yetki kararını doğrulayın.
3. Trace ile servis ve node gecikme/hatasını bulun.
4. RAG source revision veya workflow version'ını sabitleyin.
5. Model/gateway ve tool/downstream request ID'lerini ilişkilendirin.
6. Dış sistemde gerçek etkinin oluşup oluşmadığını doğrulayın.
7. Gerekirse credential/agent/workflow'u durdurun.
8. Kanıtları legal/retention kurallarına göre koruyun.
9. Kök neden ve telafi işlemini aynı incident kaydına bağlayın.

“Logda göremedik” sonucunun log yokluğu mu, sampling mi, exporter kaybı mı veya yanlış zaman aralığı mı olduğunu ayırın.

Doğrulama testleri

• Bir kullanıcı isteği model ve dış sistem etkisine kadar bulunabiliyor.
• Başarısız yetki denemesi audit'te görünüyor.
• Agent ve workflow sürümü kayda bağlanıyor.
• Retrieval source ve revision kimliği izleniyor.
• Gateway maskeleme kararı içerik ifşa etmeden görülebiliyor.
• Secret, cookie ve token log taramasında bulunmuyor.
• Audit dosyası/container kaybında korunuyor.
• OTLP backend kesintisi ana servis davranışıyla test edildi.
• Kritik audit pipeline kaybı alarm üretiyor.
• Trace sampling hata ve kritik süreçleri koruyor.
• Audit export'u salt-okunur ve ayrıca audit ediliyor.
• Retention silmesi legal hold'u koruyor.
• Saat kayması ve çoklu servis timestamp'leri tutarlı.
• Dashboard alarmları gerçek nöbet kanalına ulaşıyor.

Sonraki adımlar

• Üretim kabulü için Üretim Kurulumu Kontrol Listesi
• Agent olayları için Agent Oluşturma ve Yayınlama
• Workflow trace'i için Workflow Tasarım Rehberi
• Connector SLO'ları için Connector Yönetimi ve Senkronizasyon
• Devamlılık için Yedekleme, Geri Yükleme ve Felaket Kurtarma