Workers Observability

Workers Observability nedir?

Bir Worker yayına girdikten sonra ne olduğunu görmek gerekir: hangi istekler hata veriyor, CPU nerede harcanıyor, hangi kullanıcı hangi kod yolundan geçti.

Klasik çözüm harici bir APM aracı kurmaktır — SDK entegre et, agent yükle, ayrı bir abonelik öde. Workers Observability bunu Cloudflare’in içine taşır: tek satır yapılandırmayla loglar ve metrikler panelde birikmeye başlar.

{ "observability": { "enabled": true } }

Nasıl çalışır?

Üç katman

Yapılandırılmış log

Bu, gözlemlenebilirlikten gerçekten fayda görmenin ön koşuludur.

// Zayıf — aranabilir ama gruplanamaz
console.log("kullanıcı bulunamadı");

// İyi — alan bazında filtrelenebilir ve gruplanabilir
console.log(JSON.stringify({
  olay: "kullanici_bulunamadi",
  kullaniciId,
  istekId: request.headers.get("cf-ray"),
  yol: new URL(request.url).pathname,
}));

cf-ray başlığı her isteğe Cloudflare tarafından verilen benzersiz kimliktir; loglarında bunu taşımak bir isteğin tüm izini birleştirmeni sağlar.

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Worker’larının hata oranını ve CPU dağılımını izlemek
• Üretimde bir hatanın hangi istekte oluştuğunu bulmak
• Workers for Platforms’ta müşteri Worker’larını tek yerden izlemek
• Logları bir SIEM veya APM aracına aktarmak

Uygun olmadığı işler

• Pages projeleri. Workers Logs, Logpush, Tail Workers ve Source Maps Pages’te desteklenmiyor.
• Log koşullarına dayalı uyarı. Böyle bir özellik bulunamadı; Logpush ile dışa aktarıp uyarıyı orada kur.
• Uzun süreli saklama. Saklama süresi kısadır; arşiv için Logpush gerekir.
• Dağıtık trace (birden çok servis arası). Bu ürün Worker’a odaklıdır; uçtan uca dağıtık izleme için harici bir araç gerekir.

Somut örnekler

1. Seviye bazlı loglama

const SEVIYE = { hata: 0, uyari: 1, bilgi: 2, ayiklama: 3 };
const AKTIF = SEVIYE.bilgi;   // üretimde ayiklama'yı kapat

function log(seviye, olay, alanlar = {}) {
  if (SEVIYE[seviye] > AKTIF) return;   // CPU harcamadan çık
  console.log(JSON.stringify({ seviye, olay, ...alanlar, ts: Date.now() }));
}

export default {
  async fetch(request, env) {
    const istekId = request.headers.get("cf-ray");
    try {
      const yanit = await isle(request, env);
      log("bilgi", "istek_tamam", { istekId, durum: yanit.status });
      return yanit;
    } catch (h) {
      log("hata", "istek_hata", { istekId, mesaj: h.message, yigin: h.stack });
      return new Response("Sunucu hatası", { status: 500 });
    }
  },
};

2. Örnekleme ile log hacmini kontrol etme

Yüksek trafikte her isteği loglamak hem pahalı hem gereksizdir.

export default {
  async fetch(request, env) {
    const istekId = request.headers.get("cf-ray");
    // Başarılı isteklerin yalnızca %1'ini logla
    const orneklendi = Math.random() < 0.01;

    try {
      const yanit = await isle(request, env);
      if (orneklendi) {
        console.log(JSON.stringify({ olay: "ornek", istekId, durum: yanit.status }));
      }
      return yanit;
    } catch (h) {
      // Hatalar HER ZAMAN loglanır — örneklemeye tabi değil
      console.log(JSON.stringify({ olay: "hata", istekId, mesaj: h.message }));
      throw h;
    }
  },
};

3. Bir isteğin tüm izini birleştirme

export default {
  async fetch(request, env) {
    const istekId = request.headers.get("cf-ray");

    // Alt servislere aynı kimliği taşı
    const yanit = await fetch("https://ic-api.sirket.com/veri", {
      headers: { "x-istek-id": istekId },
    });

    console.log(JSON.stringify({
      olay: "alt_istek",
      istekId,
      hedef: "ic-api",
      durum: yanit.status,
      sure: Date.now() - baslangic,
    }));

    return yanit;
  },
};

4. Büyük nesneleri loglamamak

// YANLIŞ — 256 KB bayt bütçesini hızla doldurur
console.log(JSON.stringify({ olay: "veri", tumKayitlar }));

// DOĞRU — özet logla, ayrıntıyı sakla
console.log(JSON.stringify({
  olay: "veri",
  kayitSayisi: tumKayitlar.length,
  ilkAnahtar: tumKayitlar[0]?.id,
  boyutKb: Math.round(JSON.stringify(tumKayitlar).length / 1024),
}));

Demo 1: Observability açma ve hata ayıklama

Adım 1 — Tek satırla aç

{
  "name": "uygulamam",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-31",
  "observability": { "enabled": true }
}

wrangler deploy çıktısı — observability'nin etkin olduğunu gösteren satır

Adım 2 — Yapılandırılmış log yaz ve panelde gör

Worker → Observability → Logs: yapılandırılmış JSON logların listesi, alanların ayrıştırılmış hâlde göründüğü

Aynı ekranda bir alana göre filtre uygulanmış hâli — ör. olay=hata filtresi

Adım 3 — Kasten hata üret ve izini sür

Bir hata log kaydının detayı — mesaj, yığın izi ve istek kimliği

Tek bir istekId'ye göre filtrelenmiş kayıtlar — o isteğin tüm adımları bir arada

Adım 4 — Metrikleri incele

Observability → Metrics: invocations, error rate, CPU time ve wall time grafikleri

Adım 5 — wrangler tail ile canlı izle

npx wrangler tail --format pretty

Terminal — gerçek zamanlı akan istekler ve log satırları

Demo 2: Log hacmi ve dışa aktarım

Adım 1 — Her isteği loglayan sürümü çalıştır

Panel — belirli bir süredeki toplam log kaydı sayısı ve hacmi

Adım 2 — %1 örneklemeye geç

Aynı ölçüm örnekleme sonrası — hacmin düştüğü, hataların hâlâ tam kaydedildiği

Adım 3 — 256 KB bütçesini test et

Büyük bir nesneyi olduğu gibi loglamayı dene.

Büyük log kaydının kesildiğini veya reddedildiğini gösteren çıktı

Adım 4 — Logpush ile dışa aktar

Panel — Logpush job oluşturma; hedef olarak R2 bucket seçilmiş hâli

R2 bucket içeriği — Logpush'un yazdığı sıkıştırılmış log dosyaları ve zaman damgalı yolları

Ölçüm

Fiyatlandırma

Workers Logs, Workers planına dahildir ve log hacmi üzerinden ücretlendirilir. Saklama süresi plana bağlıdır ve ücretsiz planda kısadır — container logları için resmî rakamlar ücretsizde 3 gün, ücretlide 7 gün.

Logpush ile dışa aktarım ayrı bir kalemdir: cloudflare.com/plans sayfasında milyon istek başına 0,05 USD olarak görünüyor.

Lisanslama ve hukuki çerçeve

Workers Observability tescilli bir hizmettir; Cloudflare Hizmet Şartları kapsamındadır.

Loglarda kişisel veri. Bu, en sık gözden kaçan risktir. Loglara yazdığın her şey Cloudflare’de saklanır. IP adresi, e-posta, kullanıcı kimliği, istek gövdesi — bunlar kişisel veri olabilir ve loglama yoluyla farkında olmadan işlenmiş olur.

Pratik öneriler:

• Kullanıcı tanımlayıcılarını hash’leyerek logla
• İstek gövdesini asla olduğu gibi loglama
• Saklama süresini ihtiyacın kadar tut
• KVKK açısından log kayıtlarını da veri envanterine dahil et

Sık yapılan hatalar

Düz metin loglamak. Yapılandırılmış JSON yazmadan alan bazında filtreleme yapamazsın.

Her isteği ayrıntılı loglamak. Hem fatura hem CPU şişer. Örnekleme kullan, hataları örneklemenin dışında tut.

Büyük nesneleri olduğu gibi loglamak. 256 KB bayt bütçesini doldurur.

İstek kimliği taşımamak. cf-ray başlığını loglarına ve alt isteklerine taşımazsan bir isteğin izini birleştiremezsin.

Loglara kişisel veri yazmak. IP, e-posta ve istek gövdesi kişisel veri olabilir.

Source map yüklememek. TypeScript kullanıyorsan hata yığınları minified kod satırları gösterir.

Uyarı özelliği olduğunu varsaymak. Log koşullarına dayalı uyarı bulunamadı; Logpush ile dışa aktarıp uyarıyı orada kur.

Pages projesinde beklemek. Workers Logs, Logpush, Tail Workers ve Source Maps Pages’te yok.