# 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ç | Biçim | Ne zaman |
| --- | --- | --- |
| `/api/v1/metrics` | Prometheus metin biçimi | Prometheus ya da Grafana Alloy kullanıyorsanız |
| `/api/v1/usage` | JSON | Prometheus yoksa, Grafana Infinity eklentisiyle |

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.

![İzleme sayfası: metrik anahtarları ve bağlantı örnekleri](/docs/screenshots/panel/izleme-light@2x.png)

- 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.

![Metrik anahtarı oluşturma penceresi](/docs/screenshots/panel/izleme-anahtar-olustur-light@2x.png)

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:

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

## Prometheus

```yaml
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"]
```

```hcl
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

| Metrik | Tür | Etiketler | Ne sayar |
| --- | --- | --- | --- |
| `gurubase_llm_requests_total` | counter | `key_id`, `model`, `status` | LLM istekleri; `status`: `2xx`, `4xx`, `429_key_limit` (anahtarın kendi limiti), `429_provider` (model sağlayıcısı yoğun), `5xx`, `other` |
| `gurubase_llm_input_tokens_total` | counter | `key_id`, `model` | Modele giden token |
| `gurubase_llm_output_tokens_total` | counter | `key_id`, `model` | Modelden dönen token |
| `gurubase_llm_request_duration_seconds` | histogram | `key_id`, `model` | Başarılı LLM çağrılarının süresi |
| `gurubase_masking_requests_total` | counter | `key_id` | Maskeleme istekleri |
| `gurubase_masking_input_chars_total` | counter | `key_id` | Maskelemeye giden karakter |
| `gurubase_masking_entities_total` | counter | `key_id`, `category` | Maskelenen kişisel veri, kategoriye göre |
| `gurubase_key_info` | gauge | `key_id`, `key_name` | Anahtar adları; diğer serilere `key_id` ile bağlanır |
| `gurubase_last_ingest_age_seconds` | gauge | yok | Verinin son yenilenmesinden bu yana geçen saniye |

Etiketlerde kullanıcı, e-posta ya da IP adresi bulunmaz. Kategori adları [Kategoriler](/docs/categories/) 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:

```plaintext
# 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](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/) 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.

```json
{
  "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)](/docs/downloads/grafana/gurubase-prometheus.json): istek hızı, hata oranı, p95, veri yaşı, durum ve model kırılımları, anahtar bazında tablo.
- [Infinity panosu (JSON)](/docs/downloads/grafana/gurubase-infinity.json): aynı özet, `/api/v1/usage` üzerinden. Panel adresini pano değişkenine girin.

![Prometheus panosu: istek hızı, hata oranı, yanıt süresi ve anahtar bazında kullanım](/docs/screenshots/panel/grafana-prometheus-light@2x.png)

![Infinity panosu: seçilen aralıkta istekler, token ve maskeleme](/docs/screenshots/panel/grafana-infinity-light@2x.png)

## Alarmlar

[Alarm kuralları (YAML)](/docs/downloads/prometheus/gurubase-alerts.yml) 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](https://github.com/prometheus/blackbox_exporter) ile iki prob kurun ([örnek ayar](/docs/downloads/prometheus/blackbox.yml), [scrape ayarı](/docs/downloads/prometheus/scrape.yml)):

- 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.