Gozlemlenebilirlik

Health, readiness, metrics, audit ve hata sözleşmesi

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Endpointler

Endpoint	Anlam
/health	Sürecin yaşadığını gösteren ucuz liveness
/ready	Bağımlılık/proje durumuna göre hazır olma
Yapılandırılan metrics yolu	Prometheus çıktısı; etkin olması gerekir
<prefix>/meta	Proje metadata; yetki politikasına bağlı
<prefix>/_openapi.json	Projenin gerçek endpoint sözleşmesi

/health=200, bütün uygulamalarınızın sağlıklı olduğu anlamına gelmez. Hiç etkin app olmaması, bozuk app veya dependency hatası /ready=503 üretebilir. Readiness ayrıntıları uygulama adları ve hata tipleri verebilir; sır içermez.

OPERATOR_TOKEN, ayrıntılı readiness/metrics için ayrı kimliktir. X-Forge-Operator-Token veya uygun Bearer header kullanılabilir. Proje anahtarını process seviyesinde operatör yetkisi olarak kullanmayın. Token yoksa operatör yetkisi kazanılmaz.

HTTP hata haritası

Kod	Tipik neden	İlk kontrol
400	Hatalı JSON/parametre, eksik idempotency header	Gerçek endpoint sözleşmesi
401	Kimlik yok/geçersiz, tüketilmiş bootstrap	Doğru kimlik türü ve süre
403	Yetki, host/IP/HTTPS veya kapsam reddi	Principal + server policy
404	Endpoint/satır yok veya görünmez	Prefix, action, tenant/owner
409	Revision, rowcount, idempotency/iş çakışması	Önceki durum ve anahtar
413	Body/file/result boyutu	Hem proxy hem Forge limitleri
422	Şema/tip/alan ihlali	JSON schema ve alan allowlist
429	Rate budget aşımı	Retry-After, doğru client-IP
503	Doygunluk/bağımlılık/hazırlık sorunu	Readiness, DB, Redis, concurrency

Bunlar tipik anlamlardır; her endpoint tüm kodları üretmez. Hata body yapısı da ilgili endpoint/modelden gelir.

İstek izleme

Request ID, istemci ile server loglarını eşleştirmeyi kolaylaştırır. SDK ForgeResponse.request_id, cache_status, idempotent_replay değerlerini döndürür. Aynı retry zincirinde request ID korunur; işin idempotency anahtarıyla aynı kavram değildir.

Metrics'te istek sayısı, latency, cache etkisi ve audit queue/drop/write-failure sinyallerini birlikte izleyin. Ortalama tek başına kuyruk ve tail latency sorununu gizleyebilir. Anahtar/token, tam body ve kişisel veri gibi alanları default loglamayın.

Audit sınırı

Proje audit ve Editör güvenlik audit akışları ayrı amaçlara hizmet eder. Audit kuyruğundaki düşme veya yazma hatalarını alarm haline getirin. Uygulama düzeyindeki append-only tasarım, DB yöneticisine karşı kriptografik değiştirilemezlik veya regülasyon sertifikası değildir. İşletme erişimleri ve yedekler ayrıca korunur.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/factory.py
• main/framework/observability.py
• main/framework/audit.py
• main/docs/32-API-Semantics-and-HTTP-Contracts.md

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım