Uptime Kuma ile Telegram Bildirim Entegrasyonu Nasıl Yapılır

Yazar:komut.io ekibi Uptime Kuma ile Servis ve Web Sitesi İzleme
0 Yorum

Bir sabah işe geldiğinizde kritik bir servisin saatlerdir down olduğunu fark etmek, sysadmin kariyerinin en kötü anlarından biridir. “Neden bana bildirim gelmedi?” sorusu ise sonrasında gelen patronluk sorusundan bile daha acı gelir. İşte bu yüzden monitoring altyapısı kurmanın yarısı, doğru bildirim sistemini kurmaktan geçiyor. Uptime Kuma bu konuda gerçekten iyi bir araç; Telegram entegrasyonu ise hem ücretsiz hem de anlık push bildirimleri sayesinde SMS alternatiflerinin çok önünde.

Bu yazıda Uptime Kuma’nın Telegram bildirim entegrasyonunu A’dan Z’ye anlatacağım. Sadece “Bot API token gir, chat ID yaz, bitti” seviyesinde değil; birden fazla ekibe bildirim gönderme, farklı monitörler için farklı kanallar, mesaj formatı özelleştirme ve benim kendi ortamımda yaşadığım sorunların çözümleri dahil.

Neden Telegram?

E-posta bildirimleri gecikiyor, spam filtresine takılıyor ya da siz zaten gece 2’de e-postanıza bakmıyorsunuz. SMS ücretli ve entegrasyonu karmaşık. Slack güzel ama kurumsal lisans olmadan kısıtlı. Discord gaming odaklı algısı yüzünden bazı şirketlerde kabul görmüyor.

Telegram ise tamamen farklı: API ücretsiz, rate limit uygulamalı kullanımda yeterince yüksek, bot oluşturma 5 dakika sürüyor, iOS/Android/desktop push bildirimleri anında geliyor, mesaj formatı Markdown ve HTML destekliyor. Ayrıca Telegram gruplarını ve kanallarını bildirim hedefi olarak kullanabiliyorsunuz, bu da on-call rotasyonu yapan ekipler için oldukça kullanışlı.

Telegram Bot Oluşturma

Her şeyden önce bir bot gerekiyor. Bu kısım çoğu rehberde hızlıca geçiliyor ama bazı ince noktalar var.

Telegram’ı açın ve @BotFather ile konuşmaya başlayın. Bu resmi Telegram botu, yeni bot oluşturmanın tek yolu.

# BotFather ile konuşma adımları:
# 1. Telegram'da @BotFather araması yap
# 2. /start komutu gönder
# 3. /newbot komutu gönder
# 4. Bot için bir isim gir (örnek: "Prod Monitoring Bot")
# 5. Bot için benzersiz kullanıcı adı gir, _bot ile bitmeli (örnek: "sirket_prod_monitor_bot")

BotFather size şuna benzer bir token verecek:

7234891234:AAHx8kJl2mNpQrStUvWxYz1234567890abc

Bu token’ı güvenli bir yerde saklayın. Kimseyle paylaşmayın; token ile botunuz adına mesaj gönderilebilir. Eğer sızdıysa @BotFather‘da /revoke komutu ile iptal edip yenisini alabilirsiniz.

Şimdi Chat ID almak gerekiyor. Burada iki senaryo var: kişisel bildirim için kendi chat ID’niz, grup bildirimi için grup chat ID’si.

Kişisel Chat ID Alma

# Botunuza bir mesaj gönderin (herhangi bir şey yazın)
# Ardından bu URL'yi browser'da açın:
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool

# Çıktıda "chat" -> "id" değerini arayın
# Örnek çıktı kısımı:
# "chat": {
#   "id": 123456789,
#   "first_name": "Ahmet",
#   "type": "private"
# }

Kişisel chat ID’ler genellikle pozitif sayılardır.

Grup Chat ID Alma

Grup bildirimleri için önce botu gruba ekleyin, ardından:

# Grupta herhangi bir mesaj gönderin ya da bot'u mention edin
# Sonra getUpdates endpoint'ini çağırın
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool | grep -A5 '"chat"'

# Grup ID'leri negatif sayıdır:
# "id": -1001234567890

Eğer getUpdates boş dönüyorsa botun gruba yazma izni olup olmadığını kontrol edin. Privacy mode aktifse bot sadece / ile başlayan komutları görür. BotFather’da /mybots > botunuzu seçin > Bot Settings > Group Privacy > Turn off yaparak privacy mode’u devre dışı bırakabilirsiniz.

Telegram Kanalı için Chat ID

Kanal kullanıyorsanız (özellikle broadcast bildirimleri için iyi bir seçenek), önce botu kanala admin olarak ekleyin:

# Kanal için @username varsa direkt kullanabilirsiniz:
# chat_id: @sirket_monitoring_kanali

# Ya da numerik ID almak için:
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates"
# Kanallar için ID genellikle -100 ile başlar

Uptime Kuma’da Telegram Bildirimi Ayarlama

Artık bot token ve chat ID elimizde. Uptime Kuma’ya geçelim.

Settings > Notifications > Add Notification seçin. Notification Type olarak “Telegram” seçtiğinizde karşınıza birkaç alan çıkıyor.

Temel alanlar:

  • Bot Token: BotFather’dan aldığınız token
  • Chat ID: Kişisel, grup veya kanal ID’si
  • Message Thread ID: Forum gruplarında belirli bir thread’e göndermek için (opsiyonel)

Ayrıca “Send Silently” seçeneği var; bu seçenek aktifse mesaj bildirim sesi/titreşimi çıkarmaz. Gece saatlerinde düşük öncelikli monitörler için kullanışlı.

Notification Name alanına anlamlı bir isim verin: “Prod – DevOps Ekibi” veya “Staging – Backend Team” gibi. İleride onlarca bildirim olduğunda bu isimlendirme size çok zaman kazandırır.

Ayarları kaydettikten sonra “Test” butonuna basın. Telegram’da mesaj geliyorsa her şey yolunda demektir.

Birden Fazla Monitör, Farklı Kanallar

Gerçek dünya senaryosuna geçelim. Diyelim ki şu monitörleriniz var:

  • Production web sitesi (kritik)
  • Staging ortamı (orta öncelik)
  • Dahili araçlar (düşük öncelik)
  • Database health check (sadece DBA ekibi görsün)

Her biri için ayrı Telegram bildirimi tanımlayabilirsiniz. Uptime Kuma’da birden fazla notification profile oluşturup her monitöre farklı profil atamak mümkün.

Notification oluştururken “Default” seçeneği dikkat: Eğer bir notification’ı default yaparsanız, sonradan oluşturduğunuz her monitöre otomatik atanır. Bu bazen istemediğiniz grupların bildirim almasına yol açar. Default’u sadece en genel bildirim kanalı için aktif edin.

Aynı monitöre birden fazla bildirim de atayabilirsiniz. Monitör ayarlarında “Notifications” sekmesinde istediğiniz profilleri seçebilirsiniz. Böylece kritik bir servis düştüğünde hem DevOps grubuna hem de yöneticinin kişisel hesabına bildirim gidebilir.

Telegram Üzerinden Bildirim Testi ve Doğrulama

Uptime Kuma’nın test butonu iyi ama gerçek bir down senaryosunu simüle etmez. Manuel test için:

# Telegram API'yi direkt test etme
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" 
  -H "Content-Type: application/json" 
  -d '{
    "chat_id": "<CHAT_ID>",
    "text": "Test mesaji: Uptime Kuma entegrasyonu aktif",
    "parse_mode": "HTML"
  }'

# Başarılı yanıt şöyle görünür:
# {"ok":true,"result":{"message_id":...,"chat":{"id":...}}}

Eğer hata alırsanız:

# Yaygın hata: "chat not found"
# Çözüm: Bot'a önce mesaj gönderdiğinizden emin olun
# Ya da grup için botu gerçekten eklediğinizi kontrol edin

# Hata: "bot was blocked by the user"
# Çözüm: Kullanıcı botu engellemiş, /start göndermesi gerekiyor

# Hata: "have no rights to send a message"  
# Çözüm: Kanalda bot'un admin yetkisi yok
curl -s "https://api.telegram.org/bot<TOKEN>/getChat?chat_id=<CHAT_ID>"

Proxy Arkasında Uptime Kuma

Bazı ortamlarda Uptime Kuma’nın çalıştığı sunucu direkt internet erişimine sahip olmayabilir. Bu durumda Telegram API’ye ulaşmak için proxy gerekir.

Docker ile çalışıyorsanız:

# docker-compose.yml içinde environment değişkenleri:
version: '3.8'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    volumes:
      - uptime-kuma:/app/data
    ports:
      - "3001:3001"
    environment:
      - HTTPS_PROXY=http://proxy.sirket.local:3128
      - HTTP_PROXY=http://proxy.sirket.local:3128
      - NO_PROXY=localhost,127.0.0.1,10.0.0.0/8
    restart: always

volumes:
  uptime-kuma:

Eğer proxy NTLM authentication gerektiriyorsa (kurumsal ortamlarda yaygın):

# NTLM proxy için cntlm kurulabilir
apt install cntlm -y

# /etc/cntlm.conf ayarları:
# Username    kullanici
# Domain      SIRKET
# Password    sifre
# Proxy       proxy.sirket.local:3128
# Listen      3128

# Sonra Uptime Kuma'yı localhost:3128 üzerinden geçir

Uptime Kuma API ile Monitoring Yönetimi

Uptime Kuma’nın REST API’si var ama resmi dokümantasyonu pek gelişkin değil. Topluluk tarafından geliştirilen uptime-kuma-api Python kütüphanesi işleri kolaylaştırıyor. Özellikle çok sayıda monitör yönetiyorsanız web UI yerine script ile çalışmak çok daha verimli.

# Python kütüphanesini kur
pip install uptime-kuma-api

# Mevcut monitörleri listele ve Telegram bildirim ID'lerini görüntüle
python3 << 'EOF'
from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("http://localhost:3001")
api.login("admin", "sifreniz")

monitors = api.get_monitors()
for m in monitors:
    print(f"Monitor: {m['name']} | ID: {m['id']} | Notifications: {m.get('notificationIDList', {})}")

api.disconnect()
EOF

Toplu güncelleme senaryosu; diyelim ki yeni bir Telegram kanalı açtınız ve tüm production monitörlerine eklemek istiyorsunuz:

python3 << 'EOF'
from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("http://localhost:3001")
api.login("admin", "sifreniz")

# Önce notification ID'sini öğren
notifications = api.get_notifications()
telegram_notif_id = None
for n in notifications:
    if "Prod - DevOps" in n['name']:
        telegram_notif_id = n['id']
        print(f"Notification bulundu: {n['name']} - ID: {telegram_notif_id}")

# Production monitörlerine ekle
if telegram_notif_id:
    monitors = api.get_monitors()
    for m in monitors:
        if m.get('tags') and any(t['name'] == 'production' for t in m.get('tags', [])):
            current_notifs = list(m.get('notificationIDList', {}).keys())
            if str(telegram_notif_id) not in current_notifs:
                # Monitor'ü güncelle - mevcut ayarları koru
                print(f"Güncelleniyor: {m['name']}")

api.disconnect()
EOF

Heartbeat Monitörleri ile Cron Job İzleme

Telegram entegrasyonunun en değerli kullanım alanlarından biri heartbeat monitörleri. Cron job çalıştı mı, çalışmadı mı? Backup scripti başarıyla tamamlandı mı?

Uptime Kuma’da “Push” tipinde bir monitör oluşturun. Size özel bir URL verilecek:

http://uptime-kuma.sirket.local:3001/api/push/AbCdEf1234?status=up&msg=OK&ping=

Bu URL’yi cron job’ınıza ekleyin:

# /etc/cron.d/backup-job dosyası:
0 2 * * * root /opt/scripts/backup.sh && curl -fsS --retry 3 "http://uptime-kuma.sirket.local:3001/api/push/AbCdEf1234?status=up&msg=Backup_tamamlandi" > /dev/null 2>&1

# Eğer backup başarısız olursa curl çağrılmaz
# Uptime Kuma belirlenen süre içinde heartbeat alamazsa Telegram'a "down" bildirimi gider

Daha detaylı durum mesajı göndermek isterseniz:

#!/bin/bash
# backup.sh

UPTIME_KUMA_URL="http://uptime-kuma.sirket.local:3001/api/push/AbCdEf1234"
START_TIME=$(date +%s)

# Backup işlemleri...
/usr/bin/pg_dump -U postgres mydb > /backup/db_$(date +%Y%m%d).sql

EXIT_CODE=$?
END_TIME=$(date +%s)
DURATION=$((END_TIME - START_TIME))

if [ $EXIT_CODE -eq 0 ]; then
    curl -fsS "${UPTIME_KUMA_URL}?status=up&msg=Backup_OK_${DURATION}s&ping=${DURATION}"
else
    curl -fsS "${UPTIME_KUMA_URL}?status=down&msg=Backup_FAILED_exitcode_${EXIT_CODE}"
fi

Bu kurulumla backup başarısız olduğunda veya belirlenen sürede hiç çalışmadığında (örneğin cron daemon durdu, sunucu kapandı) Telegram’a bildirim gelir.

Bildirim Yorgunluğunu Yönetme

Çok fazla bildirim, bildirim alamamakla aynı sonucu doğurur; insanlar uyarıları yok saymaya başlar. Uptime Kuma’da bunu yönetmek için bazı ayarlar kritik:

Heartbeat interval ve retry sayısı: Bir monitörün “down” sayılması için kaç başarısız kontrol gerektiğini “Heartbeat Retry” ile ayarlayın. Kısa süreli ağ dalgalanmaları için 2-3 retry normal. Böylece 3 saniyeye geçici bir HTTP 502 için Telegram patlamaz.

Bildirim saatleri: Uptime Kuma’nın built-in maintenance window özelliği var. Planlı bakım dönemlerinde bildirimleri susturmak için kullanın:

# Maintenance window API ile oluşturma
curl -X POST "http://localhost:3001/api/maintenance" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <API_TOKEN>" 
  -d '{
    "title": "Haftalik Bakim",
    "strategy": "recurring-weekday",
    "weekdays": [0],
    "timeRange": [{"startTime": "01:00", "endTime": "04:00"}],
    "timezone": "Europe/Istanbul",
    "monitors": [1, 2, 3]
  }'

Status page ve incident yönetimi: Telegram’da sadece down/up bildirimi değil, bir status page linki de paylaşabilirsiniz. Uptime Kuma’nın status page özelliğiyle müşteri ya da ekip üyelerinize genel durum sayfası sunabilirsiniz.

Telegram Bot Güvenliği

Bot token’ı canlı ortama alırken birkaç güvenlik önlemi:

# Token'ı environment variable olarak sakla
export TELEGRAM_BOT_TOKEN="7234891234:AAHx8kJl..."

# Ya da Docker secret kullan
echo "7234891234:AAHx8kJl..." | docker secret create telegram_bot_token -

# docker-compose.yml içinde:
# secrets:
#   telegram_bot_token:
#     external: true

Uptime Kuma veritabanı (SQLite) backup alırken dikkat: Token veritabanında plaintext saklanıyor. Backup dosyalarını şifreli tutun:

#!/bin/bash
# uptime-kuma-backup.sh
BACKUP_DIR="/opt/backups/uptime-kuma"
SOURCE="/opt/uptime-kuma/data"
DATE=$(date +%Y%m%d_%H%M)

mkdir -p $BACKUP_DIR

# Sıkıştır ve şifrele
tar czf - -C $SOURCE . | 
  gpg --symmetric --cipher-algo AES256 
  --passphrase-file /root/.backup_passphrase 
  > "${BACKUP_DIR}/kuma_backup_${DATE}.tar.gz.gpg"

# 30 günden eski backupları sil
find $BACKUP_DIR -name "*.gpg" -mtime +30 -delete

echo "Backup tamamlandi: kuma_backup_${DATE}.tar.gz.gpg"

Yaygın Sorunlar ve Çözümleri

Sahadan gelen gerçek sorunlar:

“Uptime Kuma Telegram bildirimi geliyor ama mesaj karakterleri bozuk”

Türkçe karakterler bazen sorun çıkarıyor. Bu genellikle Uptime Kuma’nın monitör ismindeki özel karakterlerden kaynaklanıyor:

# Monitör isimlerinde şu karakterlerden kaçının: & < > "
# Ya da HTML encode kullanın
# Monitör adı: "Ana Sayfa & API" yerine "AnaSayfa - API" kullanın

“Chat ID değişti, artık bildirim gelmiyor”

Telegram gruplarının süper gruba dönüştürülmesi chat ID’yi değiştirebilir. Kontrol:

curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | 
  python3 -c "import sys,json; data=json.load(sys.stdin); 
  [print(u.get('message',{}).get('chat',{}).get('id','')) for u in data.get('result',[])]"

“Rate limit hatası alıyorum”

Telegram Bot API limiti: aynı chat’e dakikada 1 mesaj, grupta saniyede 20 mesaj. Onlarca monitörünüz aynı anda down olursa flood yaşanabilir:

# Uptime Kuma'nın dahili bildirim kuyruğu bunu bir ölçüde yönetir
# Ama yine de notification settings'de "Resend Notification if Down X times" 
# değerini makul tutun (örneğin her 10 kontrolde bir hatırlatma)

“Docker yeniden başladığında bildirimler geliyor”

Konteyner her restart olduğunda monitörler kısa süre “down” görünüp bildirim gönderebilir. Çözüm:

# healthcheck ve başlangıç gecikmesi ekleyin
version: '3.8'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    volumes:
      - uptime-kuma:/app/data
    ports:
      - "3001:3001"
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Sonuç

Uptime Kuma ve Telegram kombinasyonu, kurumsal monitoring araçlarının yerini tutmak için değil, hızlı ve güvenilir bir ilk savunma hattı oluşturmak için mükemmel. Bot oluşturma, chat ID alma ve Uptime Kuma’ya entegre etme süreci toplam 15 dakikayı geçmiyor. Ama asıl değer, sonrasında yaptığınız ince ayarlarda ortaya çıkıyor: doğru retry sayısı, doğru kanallar, maintenance window’lar ve heartbeat monitörleriyle cron job takibi.

Ben bu kurulumu hem küçük startup ortamlarında hem de 50+ servis izlenen daha büyük yapılarda kullandım. Küçük ortamlarda tek bir Telegram grubu yeterli olurken, büyük ortamlarda ekip bazlı kanal ayrımı ve eskalasyon mantığı kurmak gerekiyor. Uptime Kuma tek başına tam bir eskalasyon yöneticisi olmasa da Telegram’ın bot API’si üzerine kurulacak basit bir webhook köprüsüyle “ilk 5 dakikada kimse uyandıysa manager grubuna da at” gibi mantıklar da inşa edebilirsiniz.

Gece 3’te telefon titreşiminin “prod down” bildirimi getirdiği an, bu 15 dakikalık kurulumun değerini fazlasıyla anlarsınız.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir