Entegrasyonlar için olaylar, webhook'lar ve gözlemlenebilirlik
Neler değişti
Her içerik güncellemesi sürümlenir. Bir sürümü seçerek öncekiyle karşılaştırın.
Sürüm 1 → 2
Güncelleme5 ders güncellendisüre
İçerik güncellemesi. Kayıtlı öğrenciler bilgilendirildi.
Süre 13 dakikadan 17 dakikaya değişti.
Monosign'da bir webhook tanımı tek bir denetim türüne bağlıdır. O türdeki her denetim kaydı bir yürütme oluşturur ve isteği webhook servisi gönderir. Her projede iki soru gelir: testim neden boş ulaştı ve mesaj kuyruğu çöktüğünde ne olur?
::diagram api-webhook-delivery
### Belirteçler denetim kaydından gelir
Denetim yolunda Monosign her zaman beş anahtarı ve o denetim türünün veri anahtarlarını sağlar:
| Belirteç | Değer |
| --- | --- |
| `{{Audit.UserId}}` | Olayın ilgili olduğu kullanıcı |
| `{{Audit.ActorUserId}}` | İşlemi yapan kullanıcı |
| `{{Audit.SessionId}}` | Oturum |
| `{{Audit.ApplicationId}}` | Uygulama |
| `{{Audit.CreatedDate}}` | Denetim kaydının yazıldığı an |
Belirteçler `URL`, `Headers` ve `Body` içinde yerine konur. Bu beşinden biri olmayan ve denetim kaydının veri anahtarı da olmayan belirteç boş değerle değiştirilir. Bu yüzden bir örnekten `{{UserId}}` ile kopyalanan gövde alıcıya boş değerle ulaşır. `{{Audit.UserId}}` yazın.
Oturum açma akışı için küçük bir tanım şöyle görünür:
```
Type: USER_LOGIN_SUCCESS
URL: https://siem.example/hook
Method: POST
Headers: {"X-Actor-Id": "{{Audit.ActorUserId}}"}
Body: {"user": "{{Audit.UserId}}", "at": "{{Audit.CreatedDate}}"}
```
### `Execute` neyi kanıtlar, neyi kanıtlamaz
`Execute`, isteği boş bir veri kümesiyle gönderir. URL'ye ulaşılabildiğini, yöntemin ve başlıkların kabul edildiğini ve alıcının zamanında yanıt verdiğini kanıtlar. Belirteçleriniz hakkında hiçbir şey kanıtlamaz, çünkü her belirteç boş metin olarak üretilir. Belirteçleri sınamak için o türde gerçek bir denetim olayı oluşturun, örneğin bir oturum açma, ve tanımın `Items` listesinde `Send Success` durumlu satıra bakın.
### Yeniden denemeler
Başarısız gönderim, denemeler arasında sabit bir saniyelik beklemeyle en çok beş kez denenir; sonra satır `Max Try Reached` olarak işaretlenir ve `Dead Letters` altında görünür. Alıcının yinelenen bir olayı zararsız sayması bu yüzden gerekir.
### Mesaj kuyruğu çöktüğünde
::diagram obs-webhook-outage
Normal çalışmada yürütme mesaj kuyruğundan geçer. Aracı kullanılamazken **servis ana bilgisayarı** webhook'ları sınırlı gruplar hâlinde doğrudan veritabanından teslim eder. Teslimat sürer; Redis çöktüğünde de sürer.
Uygulamadaki sonuç ağla ilgilidir. Kesinti sırasında alıcınıza giden bağlantıyı servis ana bilgisayarının kendisi açar. Süreç veya sunucu başına güvenlik duvarı kuralları olan bir ortamda, servis ana bilgisayarının webhook alıcısına giden bir çıkış kuralına ihtiyacı vardır. Olaylar tam aracı çöktüğünde duruyorsa önce bu kurala bakın.
Management, System, Services altındaki `Dead Letters`, teslimata ulaşamadan duran işlerin bir insanı beklediği yerdir. Entegrasyon mühendisi listenin ne içerdiğini, neyi dışarıda bıraktığını ve her düğmenin gerçekte ne yaptığını bilmelidir.
::diagram obs-dead-letters
### Neler listelenir
| Tür | Satır ne zaman görünür | Gösterilen |
| --- | --- | --- |
| `Notifications` | Bildirimin gönderime verilmesi başarısız olmuş ve yeniden denemeleri tükenmişse | Son 30 gün |
| `User Provisions` | Provizyon satırı hata durumundaysa; örneğin 48 saat içinde tamamlanmadıysa | En çok 200 satır |
| `Webhooks` | Webhook en yüksek deneme sayısına ulaşmışsa | En çok 200 satır |
Liste her zaman oturum açtığınız kiracıya aittir.
### Boş liste sağlığın kanıtı değildir
Üç sınır, sessiz bir sekmeyi zayıf bir işaret yapar:
- Postası, SMS'i veya push'u başarısız olan bildirim **listelenmez**. Hata o kanalın geçmiş satırına yazılır ve bildirimin kendisi yine `Completed` olarak biter. Bildirimi buraya yalnızca gönderim düzeyindeki bir hata düşürür.
- Tek bir kiracıyı ve bildirimler için yalnızca son 30 günü görürsünüz.
- Sayfa uyarı vermez, posta göndermez ve izleme yapmaz. Satır yalnızca biri sayfayı açtığında görünür.
Listeyi belirli aralıklarla gözden geçirilen bir iş kuyruğu olarak ele alın; kanal geçmişiyle ve alıcı sistemlerin izlenmesiyle birlikte kullanın.
### Düğmeler ne yapar
| Tür | `Requeue` | `Discard` |
| --- | --- | --- |
| Bildirim | Yeni bir 24 saatlik süreyle beklemeye döner | Kalıcı discarded durumu |
| Kullanıcı provizyonu | Bekleme durumuna döner, provizyon servisi yeniden alır | Kalıcı discarded durumu, hiçbir şey gönderilmez |
| Webhook | Satır deneme sayısı sıfırlanarak listeden çıkar, ancak yeniden gönderilmez | Kalıcı discarded durumu |
İki düğme de tek seferde bir satırda çalışır. Requeue edilen öğe yeniden başarısız olup listeye dönebilir. Discard, satırı ve son hatasını veritabanında tutar ancak ekrandan geri alınamaz.
Webhook satırı dikkat ister: requeue edilen webhook teslim edilmediği için, kaybolan bir olayı yeniden oynatmak için `Requeue` kullanmayın. İş olayını yeniden tetikleyin ya da alıcının güncel durumu API üzerinden almasını sağlayın.
### Kim yaptı
İki işlem de satıra denetim sütunu yazmaz. Her biri Management günlüğüne bir satır yazar:
```
Dead letter requeued: webhook 7d0c... by 41aa...
Dead letter discarded: userprovision 92be... by 41aa...
```
Satır; türü (`notification`, `userprovision` veya `webhook`), satır kimliğini ve kullanıcı kimliğini taşır. Discard için tek kayıt bu satırdır. Denetçi bir satırı kimin kapattığını sorabilecekse, Management günlüklerini yanıt verebilecek kadar uzun saklayın.
Monosign, API ve Management uygulamalarında kimlik doğrulaması gerektirmeyen iki sağlık uç noktası ailesi sunar. Farklı soruları yanıtlarlar; yanlış olanı seçmek ya kör noktalara ya da gereksiz yeniden başlatmalara yol açar.
### İki aile
| Uç nokta | Neyi denetler | Yanıt |
| --- | --- | --- |
| `GET /ping/hc` | Bir denetim listesi: `Database`, `Mq`, `Cache`, `ServerGC`, `License` | 200 `{"IsHealthy":true}` ya da başarısız girdilerle 400 |
| `GET /ping/hc/mq` (yalnızca API) | Tek bir bağımlılık; `db`, `cache` ve diğerleri aynı şekilde çalışır | O tek denetimin sonucu |
| `GET /probes/ready` | Yalnızca veritabanı. Önbellek durumu bildirilir ama değerlendirilmez | 200 ya da 503 `not ready` |
| `GET /probes/live`, `/probes/startup` | Orkestratörler için | Süreç hizmet verirken 200 |
### Hangi tüketici için hangisi
- **Hata durumunda konteyneri yeniden başlatan orkestratör** `/probes/ready` kullanmalıdır. Aracı sorunu `/ping/hc` yanıtını sağlıksız yapar ve API konteynerini yeniden başlatmak aracıyı onarmaz. Hazırlık yoklaması yalnızca veritabanına bakar; yeniden başlatmanın gideremeyeceği bir arıza için yeniden başlatma tetiklemez.
- **Yük dengeleyici**, tam `/ping/hc` yanıtını kullanmalıdır; orada başarısız olan herhangi bir denetim `IsHealthy` değerini çevirir ve düğüm döngüden çıkar.
- **Tek bir bağımlılığı izleyen izleyici** hedefli biçimi kullanmalıdır; örneğin `/ping/hc/mq`.
::diagram obs-health-probes
### İzleyiciye en az altı saniye verin
`Mq` denetimi aracı üzerinden gerçek bir gidiş dönüştür ve yoklama zaman aşımı beş saniyedir. Bozulmuş bir aracı, tüm yanıtın o kadar sürmesine yol açar. Zaman aşımı altı saniyenin altında olan dış izleyici, Monosign gerçek nedeni bildiremeden kendi zaman aşımını bildirir.
### v2026.10'dan itibaren mesaj kuyruğu izleme
v2026.10'da iki şey değişti. Sağlık hataları dakika bazında sayılır ve `Status` sayfasında gün başına hatalı dakika olarak gösterilir. Mesaj kuyruğu da artık merkezi olarak denetlenmez, çünkü aracı her veri merkezine aittir. Merkezi `mq` servisini izleyen bir Monosign izleyicisi bu yüzden aracı kesintisinde sessiz kalır. Her düğümün `/ping/hc` yanıtı `Mq` girdisini taşımaya devam eder; izlemeyi düğümlere yöneltin.
Bir REST çağrısı başarısız olduğunda veya gönderim ulaşmadığında doğru bileşenin günlüğüne ihtiyacınız vardır. Monosign bunu almanın üç yolunu sunar ve her birinin açık bir sınırı vardır.
| Yol | Kapsamı | Sınırı |
| --- | --- | --- |
| Konteyner çıktısı | Her bileşen, sürekli | Kendi günlük hattınız gerekir |
| Management, System, `Logs` | Management ve ona bağlanmış servis süreçleri | API ve Account yok; yalnızca bellekte tutulur |
| Management, System, `Tracing & Log` | Seçtiğiniz uygulamalar, belirlenen dakika boyunca | Bazı uygulamaların toplayıcısı yoktur |
::diagram obs-log-paths
### Konteyner çıktısı ve JSON satırları
Her süreç günlüğünü stdout'a düz metin olarak yazar. v2026.10'dan itibaren bir bileşende `MONOSIGN_LOG_FORMAT=json` ayarlamak, o sürecin her stdout satırını tek bir JSON nesnesi yapar; JSON satırı bekleyen bir hat tam bunu ister. Kurarken üç ayrıntı önemlidir:
- Değişken bileşen başına okunur; günlük topladığınız her konteynerde ayarlayın.
- **Yalnızca stdout'u** kapsar. stderr değişmez; çalışma zamanının çökme raporu yine düz metin gelir. Hat bu birkaç satıra dayanmalıdır.
- `json` veya `text` dışındaki bir değer, tek bir uyarı satırıyla metne geri döner. Başlatma bu yüzden asla başarısız olmaz.
### Logs sayfası
Sayfa, Management sürecinin ve `MONOSIGN_LOG_HUB_URL` değişkeni Management'a yöneltilmiş servis süreçlerinin olaylarını akıtır. API ve Account uygulamaları olaylarını buraya hiç göndermez ve `Apps` onay kutuları hiçbir şeyi filtrelemez. Başarısız REST çağrılarında hata ayıklıyorsanız bu sayfa API tarafını gösteremez.
Olaylar tek bir Management örneğinin belleğinde, en çok 100 000 adet tutulur ve yeniden başlatmadan sonra kaybolur.
`Configure` altında ters okunan bir ayar vardır. `Default Level`, seçilen düzeydeki ve altındaki olayları **atar**:
| `Default Level` | Ne görürsünüz |
| --- | --- |
| `Verbose` | Verbose üstündeki her şey; sayfanın gösterebileceği en fazlası |
| `Warning` (varsayılan) | Error ve Fatal |
| `Error` | Yalnızca Fatal |
Hataları görmek için düzey Error'dan düşük olmalıdır. Ayar yalnızca sayfayı filtreler. Süreçlerin ne günlüğe yazdığını değiştirmez.
### Tracing & Log
İz, seçilen sunucu uygulamalarının tüm günlük çıktısını `Duration` dakika boyunca yakalar ve sonucu tek bir zip olarak sunar. API ve Account uygulamaları için araç budur.
Yalnızca yanıt verebilen uygulamaları seçin. `Monosign - Access Gateway` ve `Monosign - RADIUS Server` listede görünür ancak toplayıcıları yoktur; onları içeren iz hiç tamamlanmaz: `Started` olarak kalır ve `Download` uygulamaların sürdüğünü bildirir. Toplananı almak için `Download Partial` kullanın ve bir dahaki sefere bu ikisini dışarıda bırakın. Formdaki `Force Start` ve `Interval` saklanır ama kullanılmaz; izler veri saklama kurallarıyla silinmez, eskilerini kendiniz silin.
> İpucu: Araçtan değil bileşenden başlayın. API veya Account tarafı için `Tracing & Log` ya da container çıktısını kullanın. `Logs` sayfası yalnızca Management'ı ve ona bağlı servis süreçlerini gösterebilir.
Monosync'in dört sinyali vardır. Her biri tek bir soruyu iyi yanıtlar ve diğerlerinde sessiz kalır; entegrasyon mühendisinin hangisinin hangisi olduğunu bilmesi beklenir.
| Sinyal | Yanıtladığı soru | Söylemediği şey |
| --- | --- | --- |
| `/ping/hc` | Kurulum ayakta mı ve servis düğümleri canlı mı? | Belirli bir entegrasyonun çalışıp çalışmadığı |
| `Integration Logs` | Tek bir çalıştırma tek bir kayda ne yaptı? | Çalıştırmalar arası veya Monosync dışındaki her şey |
| `Monitoring` | Bir entegrasyon başarısız oldu mu veya çalışmayı bıraktı mı? | Posta yolu yapılandırılmamışsa hiçbir şey |
| `Audits` | Web arayüzünde yapılandırmayı kim değiştirdi? | Başka yollarla yapılan değişiklikler |
### Sağlık yanıtının iki alanı vardır
```
GET /ping/hc
{"IsHealthy":true,"InstanceCount":3}
```
`InstanceCount`, kendini bildiren servis düğümlerinin sayısıdır. Entegrasyonları bu düğümler çalıştırır. `{"IsHealthy":true,"InstanceCount":0}` yanıtı yine HTTP 200'dür, ancak hiçbir entegrasyon çalışamaz; örneğin servis rolü her düğümde kapalıdır. Yalnızca `IsHealthy` alanına bakan yoklama bunu kaçırır; sayının sıfır olması için de uyarı üretin.
### Bir çalıştırmayı okumak
Günlük sayfası çalıştırmadan eylemlerine, bir eylemin dokunduğu nesnelere ve tek bir nesnenin değişen değerlerine iner. İş yalnızca bazı kullanıcılar için başarısız oluyorsa buradan başlayın: neden nesne satırındadır, `Status`, `Message` ve `Exception` alanlarında; eşleme hataları da `Mapping error(s) found!` altında toplanır.
Güvenlik operasyon ekibi için iki sınır önemlidir:
- `Export All`, çalıştırmanın değişen değerlerini dışa aktarır. Hataları dışa aktarmaz.
- Monosync günlüklerini hiçbir yere göndermez. SIEM veya çalıştırmalar arası herhangi bir görünüm, günlük tablolarında salt okunur bir sorgu gerektirir. Günlük saklama süresi satırları silmeden önce okuyun.
### İzleyiciler Monosign API'sine ihtiyaç duyar
İzleyici, bir entegrasyonda hata olduğunda veya belirlenen süre boyunca çalışmadığında bir sorun açar; `[DOWN]` bildirimi, hatırlatmalar ve düzelince `[UP]` bildirimi gönderir. İzleyicilerin kendi posta sunucusu ayarı yoktur. Posta ve push, arayüz düğümünde `MONOSIGN_API_URL`, `MONOSIGN_APPID` ve `MONOSIGN_APPKEY` ile yapılandırılan Monosign API'si üzerinden gider.
Üçünden biri boşsa gönderim atlanır, ancak sorun yine de bildirildi olarak işaretlenir. O bildirimler kalıcı olarak kaybolur. Değişkenleri ekledikten sonra yalnızca yeni durum değişiklikleri ve hatırlatmalar için posta bekleyin; operasyon ekibine önceki DOWN bildirimlerinin gelmeyeceğini söyleyin.
::diagram obs-monitor-notify
### Boş Audits listesi kanıt değildir
Monosync, web arayüzünde yapılan yapılandırma değişiklikleri için denetim satırı yazar. Birkaç yol hiç satır yazmaz:
- REST API v1 üzerinden yapılan değişiklikler; örneğin bir kaynak ayarı veya değişken değeri.
- Ayarların içe aktarılması.
- Kurulum `MONOSYNC_COMMIT_DISABLE=true` ile çalışıyorsa, arayüzün kendi oluşturma ve güncelleme commit'leri.
Bir kaynağın ayarları gece değiştiyse ve `Audits` hiçbir şey göstermiyorsa, sonuç kimsenin değiştirmediği değildir. API anahtarının kimde olduğunu ve bir içe aktarma çalışıp çalışmadığını denetleyin.