Argus

Olaylar ve route şablonlama

SDK her istek için tek bir olay üretir. Olay yalnızca metadata taşır: ne gövde, ne header değeri, ne query değeri, ne de gerçek bir kimlik.

Olay şeması

  • Name
    method
    Type
    string
    Description

    HTTP yöntemi.

  • Name
    route
    Type
    string
    Description

    Şablonlanmış route. Ham URL asla gönderilmez; query ve fragment atılır.

  • Name
    statusCode
    Type
    number
    Description

    Yanıtın durum kodu.

  • Name
    durationMs
    Type
    number
    Description

    İsteğin sunucuda geçirdiği süre, milisaniye.

  • Name
    requestBytes
    Type
    number
    Description

    İstek gövdesinin boyutu, content-length başlığından. İçerik değil, boyut.

  • Name
    responseBytes
    Type
    number
    Description

    Yanıt gövdesinin boyutu. Akışlı ya da chunked yanıtlarda content-length olmadığı için 0.

  • Name
    ip
    Type
    string
    Description

    İstemci IP'si. Süreçten çıkar ama ham saklanmaz: backend, tenant'a özel bir tuz ve veritabanı dışında tutulan bir anahtarla HMAC-SHA256 ile özetleyip öyle yazar.

  • Name
    userAgent
    Type
    string
    Description

    user-agent başlığı.

  • Name
    timestamp
    Type
    string
    Description

    ISO 8601, isteğin bittiği an.

  • Name
    protection
    Type
    object
    Description

    Yalnızca bir koruma kuralı eşleştiyse bulunur: ruleId, action (delay | reject | block) ve enforced (gölgede false).

Örnek olay

{
  "method": "POST",
  "route": "/orgs/:uuid/members/:id",
  "statusCode": 201,
  "durationMs": 12.481,
  "requestBytes": 348,
  "responseBytes": 91,
  "ip": "203.0.113.7",
  "userAgent": "curl/8.4.0",
  "timestamp": "2026-09-12T09:41:02.118Z",
  "protection": {
    "ruleId": "…",
    "action": "reject",
    "enforced": false
  }
}

Route şablonlama

route bir şablondur, ham URL değil. Gerçek kimlikler süreçten çıkmaz ve route kardinalitesi düşük kalır.

İstek path'iBildirilen route
/users/123/users/:id
/users/123?token=abc/users/:id
/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/7/orgs/:uuid/members/:id
/docs/507f1f77bcf86cd799439011/docs/:objectid
/orders/01HQ3M7XK9ZB4F2N8YQWE5TVDC/orders/:ulid
/reset/9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c/reset/:hex
/users/ada@example.com/users/:email
/p/aB3xK9z/p/:token
/health, /users/me, /api/v1/usersdeğişmez

Kurallar segment başına uygulanır: yalnızca rakam → :id, UUID → :uuid, 24 hex → :objectid, ULID → :ulid, 16+ hex → :hex, e-posta (ham ya da %40 kodlu) → :email, rakam içeren karışık büyük-küçük harf ya da uzun alfanümerik → :token.

Şüphede kalınca şablonlanır: gerçek bir kimliği sızdırmak bir route adını kaybetmekten kötüdür. Her desen için hem "şablonlanmalı" hem "gerçek route adına dokunulmamalı" testi vardır; /health, /v2, /me bozulmaz.

ignorePaths

ignorePaths tam eşleşme ya da segment öneki olarak çalışır: /health, /health/live'ı da kapsar ama /healthcheck'i kapsamaz. Atlanan path için olay üretilmez ve koruma kuralları uygulanmaz. Sağlık ucu, metrik ucu ve yük dengeleyici probları için düşünülmüştür.

Ne saklanır, ne saklanmaz

  • Saklanır: yukarıdaki alanlar; IP yalnızca tenant tuzu + sunucu anahtarıyla HMAC'lenmiş hâliyle.
  • Saklanmaz: istek/yanıt gövdesi, header değerleri, query değerleri, gerçek path kimlikleri, çerezler, yetki jetonları.
  • Hiç toplanmaz: kullanıcı kimliği. SDK kimlik görmez; kullanıcı başına kota bu yüzden yoktur.

Uçtan uca test gövdeye, query'ye ve path'e kanarya değerler koyup backend'e düşen hiçbir olayda görünmediklerini doğrular.