Grafana ile izleme

Kurumunuzun gateway kullanımını Prometheus ya da Grafana Infinity ile canlı izleyin; hazır pano ve alarm kuralları.

Gateway, kurumunuzun kullanım metriklerini iki uçtan yayınlar. İkisi de aynı veriyi verir; hangisini kullanacağınız Grafana’nın arkasında ne çalıştığına bağlıdır.

Uçlar panel adresinde çalışır (örnek: https://gateway-tr.gurubase.io). Yalnız kendi kurumunuzun verisi döner; istekteki hiçbir parametre bunu değiştirmez. Veriler yaklaşık 15 saniyede bir yenilenir.

Metrik anahtarı

Uçlar, panelden ürettiğiniz yalnız okuma yetkili bir anahtarla çalışır. Anahtarı Ayarlar > İzleme sayfasından kurum yöneticisi oluşturur.

• Anahtar yalnız metrik okur. Kuruma özel regex yönetimi gibi başka bir işlem yapamaz.
• Son kullanma tarihi zorunludur, en uzun bir yıldır.
• İsteğe bağlı: izinli adres listesi. Anahtar yalnız listedeki adreslerden (ör. 203.0.113.10 ya da 198.51.100.0/24) kullanılabilir.
• Ham anahtar yalnız oluşturulduğu anda bir kez gösterilir.

Anahtarı ayar dosyasına yazmak yerine yalnız Prometheus’un okuyabildiği ayrı bir dosyada saklayın. Hatalı, süresi dolmuş, iptal edilmiş ya da izinli adres dışından kullanılan anahtar aynı 401 yanıtını alır.

Denemek için:

curl -H "Authorization: Bearer $GURUBASE_METRICS_KEY" \
  https://gateway-tr.gurubase.io/api/v1/metrics

Prometheus

scrape_configs:
  - job_name: gurubase
    scheme: https
    metrics_path: /api/v1/metrics
    scrape_interval: 30s
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/gurubase-metrics.key
    static_configs:
      - targets: ["gateway-tr.gurubase.io"]

prometheus.scrape "gurubase" {
  targets         = [{"__address__" = "gateway-tr.gurubase.io"}]
  scheme          = "https"
  metrics_path    = "/api/v1/metrics"
  scrape_interval = "30s"
  authorization {
    type             = "Bearer"
    credentials_file = "/etc/alloy/gurubase-metrics.key"
  }
  forward_to = [prometheus.remote_write.default.receiver]
}

Metrikler

Etiketlerde kullanıcı, e-posta ya da IP adresi bulunmaz. Kategori adları Kategoriler sayfasındaki adlardır.

gurubase_last_ingest_age_seconds birkaç dakikayı geçerse veri bayattır. Bu durumda düz çizgi “trafik yok” anlamına gelmez; alarmı bu seriye kurun.

Örnek sorgular:

# Son 5 dakikada hata oranı
sum(rate(gurubase_llm_requests_total{status!="2xx"}[5m]))
  / sum(rate(gurubase_llm_requests_total[5m]))

# p95 yanıt süresi
histogram_quantile(0.95,
  sum by (le) (rate(gurubase_llm_request_duration_seconds_bucket[5m])))

# Anahtar adıyla istek sayısı
sum by (key_id) (increase(gurubase_llm_requests_total[1h]))
  * on (key_id) group_left (key_name) max by (key_id, key_name) (gurubase_key_info)

Grafana Infinity (Prometheus yoksa)

Infinity eklentisiyle bir veri kaynağı ekleyin:

• Kimlik doğrulama: Bearer Token, değer metrik anahtarınız.
• İzinli adres: panel adresiniz (ör. https://gateway-tr.gurubase.io).
• URL: https://gateway-tr.gurubase.io/api/v1/usage?window=24h

window değeri 1h, 6h, 24h, 7d ya da 30d olabilir. Yanıt, toplamların yanında window.points altında seçilen aralığın zaman dilimlerine bölünmüş sayılarını da taşır; Infinity sayaçlardan hız hesaplayamadığı için grafikler bu diziden çizilir.

{
  "last_ingest_age_seconds": 10,
  "keys": [{ "key_id": "vk-web", "key_name": "Web asistanı" }],
  "llm": [
    {
      "key_id": "vk-web",
      "model": "gpt-4o-mini",
      "requests_2xx": 252,
      "requests_4xx": 0,
      "requests_429_key_limit": 6,
      "requests_429_provider": 2,
      "requests_5xx": 1,
      "requests_other": 0,
      "input_tokens": 219137,
      "output_tokens": 83576
    }
  ],
  "latency": [
    { "key_id": "vk-web", "model": "gpt-4o-mini", "count": 252, "p50_seconds": 1.32, "p95_seconds": 4.35 }
  ],
  "window": {
    "name": "1h",
    "step_seconds": 60,
    "points": [{ "ts": "2026-10-23T11:20:00.000Z", "requests": 48, "errors": 2, "input_chars": 83120 }]
  }
}

latency alanındaki yüzdelikler gateway’in son açılışından bu yana birikmiş gözlemlerden tahmin edilir. Kısa aralıklı yüzdelik için Prometheus ucunu kullanın.

Hazır panolar

Panoları Grafana’da Dashboards > New > Import ile içe aktarın ve veri kaynağınızı seçin.

• Prometheus panosu (JSON): istek hızı, hata oranı, p95, veri yaşı, durum ve model kırılımları, anahtar bazında tablo.
• Infinity panosu (JSON): aynı özet, /api/v1/usage üzerinden. Panel adresini pano değişkenine girin.

Alarmlar

Alarm kuralları (YAML) yedi kural içerir: hata oranı %5’in üstünde, model sağlayıcısı yoğun (429_provider), bir anahtar kendi limitine takılıyor (429_key_limit, bilgi seviyesi), p95 10 saniyenin üstünde, veri 5 dakikadan eski, metrik ucuna ulaşılamıyor, erişilebilirlik probu başarısız. Hata oranı, anahtarın kendi limitine takılan istekleri saymaz. Eşikler başlangıç değeridir; trafiğinize göre ayarlayın.

Trafik yokken erişilebilirlik

Sayaçlar yalnız trafik olduğunda artar. Trafik yokken de sistemin ayakta olduğunu görmek için blackbox_exporter ile iki prob kurun (örnek ayar, scrape ayarı):

• API adresinin /health ucu. Anahtar gerekmez.
• Kendi API anahtarınızla küçük bir /mask çağrısı. Sentetik bir test numarası gönderir ve yanıt maskeli dönmezse başarısız sayılır. Her prob kotanızdan yaklaşık 14 karakter kullanır.