> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/observability/metrics-logs-traces.md). # Metric, log ve trace Kangal ilişkili fakat bilinçli olarak ayrı tutulan sinyal yolları sağlar. Prometheus metrikleri alarm üretmek için, gateway analitiği sınırlı operasyonel özetler için, yakın trafik istek tanılaması için, korelasyonlu olaylar ise yapılandırılmış saklama süresi boyunca istek ve trace kimliklerini birleştirmek için kullanılır. ## Prometheus metrikleri Prometheus `GET /metrics` endpoint'ini scrape eder: ```yaml scrape_configs: - job_name: kangal metrics_path: /metrics static_configs: - targets: ['kangal-api:8000'] ``` ```bash curl -fsS "$KANGAL_URL/metrics" | grep '^kangal_' ``` Bu route'ta uygulama düzeyinde authentication dependency yoktur. Özel ağda tutun, ingress policy veya proxy authentication ile koruyun ve internete doğrudan açmayın. Temel seriler: | Metrik | Tür ve kullanım | | ------------------------------------------- | ------------------------------------------------------------------------------------ | | `kangal_requests_total` | Method, path, status, tenant, gateway, workspace ve route etiketli istek sayacı. | | `kangal_request_latency_seconds` | Uçtan uca istek gecikmesi histogramı. | | `kangal_route_latency_seconds` | Route bazlı SLO incelemesi için gecikme histogramı. | | `kangal_inflight_requests` | Devam eden istek gauge'u. | | `kangal_rate_limit_hits_total` | Rate limit nedeniyle reddedilen istekler. | | `kangal_plugin_errors_total` | Plugin hataları. | | `kangal_plugin_latency_seconds` | Plugin çalışma süresi. | | `kangal_upstream_errors_total` | Upstream hataları. | | `kangal_observability_writes_dropped_total` | `reason="timeout"` veya `reason="failure"` nedeniyle kaybedilen korelasyon olayları. | Bazı deployment'lar ilgili worker'lar etkinse background job metrikleri de yayınlar. Opsiyonel collector'ların bulunduğunu varsaymak yerine canlı `/metrics` çıktısını inceleyin. Örnek PromQL: ```promql # Gateway bazında istek hızı sum by (tenant_id, gateway_id) (rate(kangal_requests_total[5m])) # 5xx yüzdesi 100 * sum(rate(kangal_requests_total{status=~"5.."}[5m])) / clamp_min(sum(rate(kangal_requests_total[5m])), 1) # p95 istek gecikmesi histogram_quantile( 0.95, sum by (le, tenant_id, gateway_id) ( rate(kangal_request_latency_seconds_bucket[5m]) ) ) # Korelasyon olayı persistence hataları sum by (reason) (rate(kangal_observability_writes_dropped_total[5m])) ``` Path, tenant, gateway, workspace ve route gibi label'lar yüksek cardinality oluşturabilir. Recording rule'larda toplulaştırma yapın, kullanıcı üretimi kimlikleri route template'lerine koymayın ve Prometheus retention/remote-write sınırlarını tenant sayısına göre belirleyin. ## Gateway analitiği `GET /api/v1/admin/gateways/{gateway_id}/overview`, `analytics` bloğunda yedi günlük istek sayısı, hata oranı, ortalama ve p95 gecikme, rate-limit hit'leri ve yavaş route/plugin verilerini döndürür. ```bash curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/overview" \ | jq '.analytics' ``` Hata sayacı 400 ve üzeri yanıtları içerir; p95 değeri yapılandırılmış gecikme aralıklarından tahmin edilir. Analitik bloğu tanılama amaçlı yedi günlük bir özettir: yakın istekler alım gecikmesinden sonra görünebilir, saklanan örnekler her olayı kapsamayabilir ve sonuç olay bazında kesin bir kayan pencere değildir. Bütünlük gerektiğinde kesin sorgu semantiği belgelenmiş bir kaynak kullanın. ## Yakın zamanlı trafik logları Desteklenen tenant-aware API: ```http GET /api/v1/admin/gateways/{gateway_id}/traffic/recent?limit=50 ``` `limit` 1 ile 200 arasında olmalıdır. Endpoint, çağıranın gateway'i görebildiğini doğrular ve bu sınıra kadar mevcut en yeni tanılama kayıtlarını döndürür. ```bash curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/traffic/recent?limit=100" \ | jq '.logs[] | {timestamp, method, path, status_code, latency_ms, upstream}' ``` Trafik sonucu timestamp, method, path, route path/ID, tenant/gateway ID, status, latency, upstream, plugin'ler, client IP ve kullanıcı kimliği içerebilir. Yakın trafik API'ı yakalanan header'ları döndürmez. Haricî log hedefleri farklı alanlara sahip olabilir; bu hedeflere erişimi sınırlandırın ve upstream kaynaklı hassas değerleri temizleyin. Yakın trafik, sınırlı ve en iyi çabayla sunulan bir tanılama görünümüdür. Saklama süresi, veri alım sağlığı, hizmet değişiklikleri veya istenen sınır nedeniyle kayıtlar gecikebilir, atlanabilir ya da kullanılamayabilir. Endpoint eksiksiz yakalama veya kalıcı saklama garantisi vermez; onu faturalandırma kaydı, uyumluluk arşivi ya da listelenmeyen bir isteğin gerçekleşmediğinin kanıtı olarak kullanmayın. ## Uygulama logları Kangal standard output'a yapılandırılmış JSON yazar. Yaygın alanlar `ts`, `level`, `msg` ve `logger`'dır; mevcut olduğunda request, tenant, gateway ve admin bağlamı eklenir. ```bash kubectl logs -n kangal deploy/kangal-api --since=30m \ | jq 'select(.level == "ERROR")' kubectl logs -n kangal deploy/kangal-api --since=30m \ | jq 'select(.request_id == "destek-kaydi-8472")' ``` Opsiyonel best-effort Elasticsearch log handler'ı `ELASTIC_HOST`, `ELASTIC_PORT`, `ELASTIC_SCHEME` ve `ELASTIC_INDEX` ile ayarlanır. Delivery hatası uygulama işleminin başarısız olduğunun kanıtı değildir; hedef sistemi ayrıca izleyin. ## Logging plugin'leri Gateway policy'leri istek loglarını HTTP, file, TCP, UDP, Kafka, Datadog veya OpenTelemetry odaklı bir HTTP receiver'a gönderebilir. Her hedefi request-path performans bütçesinin parçası olarak değerlendirin. Operasyonel varsayılanlar ve uyarılar: * Header yakalama varsayılan olarak kapalıdır. Yalnızca açık allow-list ve redaksiyon gereksinimleriyle etkinleştirin. * Sink hataları varsayılan olarak isteği bozmaz (`fail_on_error: false`). Hedef hatasını kullanıcı isteği hatasına dönüştürmek bilinçli bir erişilebilirlik kararı olmalıdır. * Ağ sink'leri istek işlenirken çalışır; production öncesi timeout ve receiver hata davranışını benchmark edin. * Kafka delivery, deployment tarafından producer enjekte edilmediyse Python Kafka istemcisini gerektirir. * File logging API process'inin filesystem'ine yazar. Kalıcı volume ve rotation kullanın veya merkezi hedefi tercih edin. ## Trace aktarımı Kangal W3C `traceparent` kabul eder, yoksa veya geçersizse trace/span kimlikleri üretir ve korelasyon bağlamını upstream'e taşır. OpenTelemetry logging plugin'i varsayılan `kangal-gateway` service adı ve `kangal.gateway.request` span adıyla HTTP üzerinden JSON span envelope'u gönderir. Plugin'in HTTP JSON span envelope'unu kabul eden bir receiver yapılandırın ve ortamın gerektirdiği collector/tracing backend'i çalıştırın. Sampling policy'leri 0 ile 1 arasında oran kabul eder ve random/hash tabanlı karar verebilir; bir karar header'ı isteğin sample edilip edilmediğini gösterebilir. Tek isteği sinyaller arasında izlemek için: 1. Gateway yanıtındaki `X-Request-ID` değerini alın. 2. Trace ve span kimlikleri için `/api/v1/admin/observability/requests/{request_id}` sorgulayın. 3. Yapılandırılmış uygulama loglarında `request_id` arayın. 4. Tracing receiver'da `trace_id` ile arama yapın. 5. Olay gecikmesini aynı zaman aralığındaki Prometheus ve yakın trafik verisiyle karşılaştırın. ## Güvenlik ve veri işleme Korelasyonlu gözlemlenebilirlik olayları payload içermez: istek/yanıt gövdesi, kimlik bilgisi ve header saklanmaz. Trafik logları ve harici logging plugin'leri ayrıdır; policy ayarına göre daha fazla ayrıntı taşıyabilir. Bir sink'i etkinleştirmeden önce: * Path, query string, header, client IP ve kullanıcı kimliklerini kurumun veri politikasına göre sınıflandırın. * `Authorization`, cookie, API key ve credential materyalini log payload'ından çıkarın. * Aktarımı şifreleyin, receiver'ı doğrulayın ve tenant erişimini sınırlayın. * Receiver retention'ını Kangal retention ve silme yükümlülükleriyle uyumlu hale getirin. * Sentetik bir istek gönderip hem delivery'yi hem redaksiyonu doğrulayın. ## Sorun giderme | Belirti | Kontroller | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prometheus scrape edemiyor | Prometheus ağından `/metrics` erişimini, ingress ve network policy'yi test edin. Route bearer token kullanmaz. | | Dashboard ile overview farklı | Farklı store ve aggregate semantiği kullanırlar. Zaman aralığını ve scrape boşluklarını karşılaştırın. | | Yakın trafikte istekler eksik | İstenen zamanı ve sınırı, telemetri alım sağlığını, saklama süresini, düşen yazma metriğini ve yakın hizmet değişikliklerini kontrol edin. Bu tanılama görünümünde eksik kayıtlar olabilir. | | Trace backend'de span yok | Sampling, receiver uyumluluğu, endpoint erişimi ve plugin hata metrik/loglarını doğrulayın. | | İstek başarılı ama sink'te log yok | `fail_on_error: false` iken sink hatası isteği bozmaz. Hedefi ve plugin hatalarını inceleyin. | | Metrik cardinality hızla artıyor | Dinamik label'ları aggregate edin, normalize route path kullanın ve recording rule ekleyin. | | Korelasyonlu istek araması seyrek | `kangal_observability_writes_dropped_total` ve tenant retention'ını kontrol edin. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/observability/metrics-logs-traces.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.