AI Caginda Loglama: evlog ile Structured Observability

AI Caginda Loglama: evlog ile Structured Observability

Bir AI agent'i dusun. Geceleri calisiyor, binlerce API cagrisi yapıyor, veritabanlarini sorguluyor ve sabaha karsi bir rapor uretiyor. Ama bir sey ters gidince ne oluyor? Gelistirici olarak karsimiza binlerce console.log satiri cikiyor. Her biri bir parca bilgi tasiyor ama hicbiri butunu gostermiyor. Agent neden basarisiz oldu? Hangi asamada hata verdi? Cozum ne? Bu sorulara cevap bulmak icin saatlerce log kazmamiz gerekiyor. Iste tam da bu noktada evlog devreye giriyor.

evlog, modern TypeScript ekosisteminin en iddiali loglama kutuphanelerinden biri. Zero dependency, yaklasik 6 KB gzip boyutu ve istek basina 3 mikrosaniye gecikme ile geleneksel loglayicilari geride birakiyor. Ama asil farki hizinda degil, paradigmasinda. Wide events (genis olaylar) ve structured errors (yapilandirilmis hatalar) kavramlarini merkeze alan evlog, loglamayi bir hata ayiklama aracindan ote, AI-native bir gozlemlenebilirlik (observability) platformuna donusturuyor. Bu yazida evlog'un arka planini, teknik mimarisini, AI gozlemlenebilirligi ile iliskisini ve mevcut ekosistemden nasil ayrildigini derinlemesine inceliyoruz.

Structured logging, geleneksel loglama karmasasini duzenli, sorgulanabilir veriye donusturur.

Kokler: Hugo Richard ve Logging Sucks Hareketi

evlog'un hikayesi, Vercel'de Nuxt ekibinde calisan Hugo Richard'in kisisel deneyimleriyle basliyor. Yazilim muhendisi ve tasarimci kimligiyle one cikan Richard, modern web uygulamalarinin loglama ihtiyaclarini karsilayan mevcut araclarin yetersizligini fark ediyor. console.log yiginlari, pino'nun parcali ekosistemi, winston'un yasinmis yapisi... Hepsi birer cozum sunuyor ama hicbiri TypeScript-first, framework-agnostic ve AI-hazir bir butun sunmuyor.

Richard'in ilham kaynaklarindan biri, Nominal'in kurucusu Boris Tane'in Logging Sucks manifestosu. Tane, gozlemlenebilirlik dunyasinda devrim yapan bir arguman sunuyor: Geleneksel loglar ve metrikler, modern dagitik sistemlerin karmasasini cozmek icin yetersiz. Bunun yerine her istekte (veya islemde) tek, baglam dolu bir olay yayinlamak gerekiyor. Bu olay, Tane'nin deyisiyle arbitrarily-wide event (keyfi genislikte olay), o istekle ilgili tum baglami tek bir JSON yapisi icinde birlestiriyor. Sonradan bu yapiyi parcalayip metrik ve iz (trace) turetmek mumkun, ama tersi mumkun degil.

evlog tam olarak bu felsefeyi uyguluyor. Tane'in teorik cercevesini, Richard'in modern TypeScript pratigiyle birlestirerek, hem gelistirici deneyimi hem de makine okunabilirligi acisindan optimize ediyor.

Geleneksel Loglama Neden Yetersiz?

Loglama konusunda uzun yillardir suregelen bir kabul var: Daha fazla log, daha iyi gozlemlenebilirlik. Ama gercek tam tersi. Her console.log bir parca bilgi tasir, ama ayni zamanda bir parca gurultu de ekler. Uc istekli bir odeme sistemini dusunelim:

// Geleneksel yaklasim
console.log('User authenticated:', user.id)
console.log('Cart items:', cart.items)
console.log('Payment processing...')
console.log('Payment failed:', error.message)
console.log('Status code:', 402)

Bu bes satir, bes ayrı log kaydi. Kibana veya benzeri bir aracta arama yaparken, bu satirlari birlestirmek icin correlation ID gibi mekanizmalar gerekiyor. Ama istek sayisi binlerce oldugunda, bu birlestirme islemi pahali ve hataya acik hale geliyor. Ustelik her satir, istegin tam baglamindan yoksun. Odeme basarisiz oldugunda neden basarisiz oldugunu anlamak icin bu satirlari tek tek incelemek zorundayiz.

evlog'un cozumu, bu bes satiri tek bir wide event'te birlestirmek:

import { useLogger, createError } from 'evlog'

const log = useLogger(event)
log.set({ user: { id: user.id, plan: user.plan } })
log.set({ cart: { items: 3, total: 9999 } })

if (!charge.success) {
  throw createError({
    status: 402,
    why: 'Card declined by issuer (insufficient funds)',
    fix: 'Try a different payment method or contact your bank',
    link: 'https://docs.example.com/payments/declined'
  })
}

Bu kod calistiginda, basarili durumda tek bir INFO olayi uretiliyor. Icinde kullanici bilgisi, sepet detaylari, istek ID'si, sure ve diger tum baglam bir arada. Hata durumunda ise tek bir ERROR olayi, hata mesajinin yaninda neden basarisiz oldugu (why), nasil duzeltilecegi (fix) ve ilgili dokumantasyon baglantisi (link) ile birlikte geliyor. Bu, sadece gelistiriciler icin degil, ayni zamanda AI agent'lar icin de kritik bir avantaj.

Karpathy'nin autoresearch projesini hatirlayalim. AI agent'lar geceleri calisip kendi kendine arastirma yapiyor. Peki bu agent'lar bir hata ile karsilastiginda ne yapacak? Geleneksel loglari okuyup anlamaya calisacaklar. Ama loglar yapilandirilmadiginda, agent'in hata ayiklama yetenegi ciddi sekilde kisitlaniyor. evlog'un why ve fix field'lari, tam da bu noktada agent'lara dogrudan eyleme gecirilebilir baglam sunuyor.

Wide Events: Tek Bir Olayda Tum Hikaye

Wide event kavrami, gozlemlenebilirlik alaninda giderek yayginlasan bir yaklasim. Honeycomb gibi modern gozlemlenebilirlik platformlarinin da benimsedigi bu yaklasimda, her islem veya istek icin tek, baglam dolu bir olay kaydediliyor. Bu olay, key-value ciftleri seklinde tum ilgili veriyi iceriyor. Sonradan bu veriyi sorgulayarak metrikler, dagilimlar ve korelasyonlar turetilebiliyor.

evlog bu kavrami uc farkli modda sunuyor:

1. Simple Logging (log.*): Tek cagrida tek olay. Geleneksel console.log veya pino yerine gecer. Hemen hemen ayni hizda calisir ama yapilandirilmis veri sunar.
2. Wide Events (createLogger / createRequestLogger): Baglami biriktirir, istediginiz zaman tek bir olay olarak yayinlar. Arka plan isleri (background jobs), kuyruk sistemleri veya manuel HTTP handler'lari icin idealdir.
3. Framework Middleware (useLogger): Framework entegrasyonlariyla otomatik yonetilen wide event'ler. Nuxt, Next.js, Express, Hono gibi 13'ten fazla framework destekleniyor. Istek baslar baslamaz logger olusur, yanit dondugunde otomatik yayinlanir.

Bu uc modun ayni drain pipeline'i, ayni redaction (hassas veri maskeleme) ve ayni tip sistemi altinda calismasi, evlog'un en guclu yonlerinden biri. Projenin farkli katmanlarinda farkli modlari kullanabilirsiniz, ama hepsi ayni hedefe ulasir.

Wide events, modern dagitik sistemlerin karmaşık katmanlarini tek bir yapilandirilmis olayla birleştirir.

13 Framework, Tek API: evlog'un Ekosistemi

Bir loglama kutuphanesinin basarisi, destekledigi ekosistemle orantili. evlog bu konuda pino ve winston'u geride birakiyor. 13'ten fazla framework icin resmi entegrasyon sunuyor:

• Meta-framework'ler: Nuxt (modul olarak), Next.js (fabrika), SvelteKit (hooks), React Router (middleware), TanStack Start
• API sunuculari: Express (middleware), Fastify (register), Hono (middleware), Elysia (plugin), NestJS (modul)
• Edge ve sunucusuz: Cloudflare Workers, AWS Lambda, Nitro v2/v3
• Standalone ve tarayici: Duz TypeScript script'ler, CLI araclari, istemci tarafi loglama

Bu genis framework destegi, evlog'un sadece bir loglayici degil, ayni zamanda bir platform vizyonu oldugunu gosteriyor. Nuxt projesinde modules: ['evlog/nuxt'] ekleyip zero-config calismaya baslamak mumkun. Next.js'te createEvlog() fabrikasiyla ayni deneyimi yasayabiliyorsunuz.

Ozellikle Zed 1.0 gibi modern gelistirici araclarinin yukselisini dusundugumuzde, editorden bagimsiz, framework-agnostic araclarin onemi artiyor. evlog, tam da bu ihtiyaca cevap veriyor. Nuxt'te mi calisiyorsunuz, Express mi? Fark etmiyor, ayni API'yi kullaniyorsunuz.

AI Observability: Kara Kutu LLM'leri Aydinlatan Isik

Buyuk Dil Modelleri (LLM'ler) icin loglama, geleneksel yazilim loglamasindan farkli zorluklar iceriyor. Bir LLM cagrısinda neler oluyor? Kac token harcandi? Hangi araclar (tools) cagrildi? Streaming ne kadar surdu? Bu bilgileri elle takip etmek zor ve hataya acik.

evlog, Vercel AI SDK ile entegre calisan createAILogger API'si ile bu sorunu cozuyor. Tek satirlik bir sarmalama (wrap) ile LLM cagrilarinizi gozlemlenebilir hale getiriyorsunuz:

const ai = createAILogger(log, {
  cost: { 'claude-sonnet-4.6': { input: 3, output: 15 } }
})

const result = await streamText({
  model: ai.wrap('anthropic/claude-sonnet-4.6'),
  messages
})

Bu entegrasyon sayesinde, LLM cagrilarinizin token kullanimi, maliyet hesaplamasi, arac cagri zinciri ve streaming metrikleri ayni wide event icinde toplaniyor. AI agent'lar icin bu, kendi performanslarini analiz etmek ve optimize etmek icin gerekli veriyi sagliyor.

Kimi K2.6'nin 300 paralel ajan gibi mimarileri dusunelim. Her ajan bagimsiz calisiyor, kendi loglarini uretiyor. Bu loglari yapilandirilmamis tuttugumuzda, ajanlar arasi korelasyonu ve hata ayiklamayi gerceklestirmek neredeyse imkansiz. evlog'un log.fork() API'si, alt islemler (sub-operations) icin cocuk logger'lar olusturup, bunlari ana istekle _parentRequestId uzerinden iliskilendirmeyi sagliyor. Bu, paralel ajan sistemlerinde hata izleme ve performans analizi icin kritik.

Bir adim oteye gidelim. evlog'un structured error formati, AI agent'larin sadece hatalari degil, ayni zamanda cozum onerilerini de okumasini sagliyor. Bir odeme basarisiz oldugunda, agent sadece Card declined mesajini degil, ayni zamanda why: Card declined by issuer (insufficient funds) ve fix: Try a different payment method bilgilerini de aliyor. Bu, agent'in otomatik olarak kullaniciya cozum sunmasini veya alternatif odeme yontemi onermesini saglayabilir.

AI gozlemlenebilirligi, LLM cagrilarinin kara kutu yapısını yapılandırılmış olaylara dönüştürür.

Uretime Hazir: Drain Pipeline, Sampling ve Audit

Loglama kutuphanesi seciminde performans kadar, uretim ortaminda nasil davrandigi da onemli. evlog, drain pipeline mimarisi ile loglari asla yaniti bloklamadan isler. Batch'leme, ustel geri cekilme (exponential backoff) ve jitter ile retry, coklu hedefe yayin (fan-out) gibi yeteneklerle birlikte geliyor.

Desteklenen drain hedefleri arasinda Axiom, OTLP (OpenTelemetry), Sentry, PostHog, Better Stack, dosya sistemi ve ozel drain'ler bulunuyor. Istemci tarafindan sunucuya log tasma (client-to-server logging) da destekleniyor. Tarayici tarafinda sendBeacon ile sayfa kapanirken bile olay kaybetmemek mumkun.

Log hacmini yonetmek icin evlog, iki katmanli ornekleme (sampling) sunuyor. Head sampling, seviyeye gore oran belirlemenizi sagliyor (ornegin INFO'un %10'unu, WARN'in %50'sini, ERROR'un hepsini tut). Tail sampling ise, belirli kriterlere uyan olaylari (400 hatasi, 1 saniyeden uzun istek, kritik yol) kosulsuz olarak sakliyor. Bu, gurultuyu azaltirken kritik sinyalleri kacirmamanizi sagliyor.

Audit loglari (kim ne yapti) icin de ozel bir katman mevcut. HMAC imzalari veya hash zinciri ile degisim korumasi (tamper-evident) sunan audit sistemi, action, actor, target, outcome gibi sabit bir semaya sahip. Idempotency key'ler ile guvenli retry de destekleniyor. Bu, finansal islemler, GDPR silme talepleri veya yetki degisiklikleri gibi duzenleyici gereksinimleri olan projeler icin hayat kurtarici.

Karsilastirma: evlog vs Ekosistem

Bir loglama kutuphanesi secimi, projeye bagli olarak degisir. evlog ekibi, karsilastirmayi samimiyetle yapmis:

pino'ya karsi: evlog, ayni hiz sinifinda calisirken, yapilandirilmis hatalar, redaksiyon ve wide event'leri yerlesik olarak sunuyor. pino'da bunlar icin pino-pretty, pino-http ve ozel transport'lari bir araya getirmeniz gerekiyor. Wide event dongusunde evlog, pino'dan 7.7 kat daha hizli (1.58M ops/s vs 206K ops/s). Tek basina log.info('hello') cagrisinda pino hafif avantajli olabilir, ama gercek uygulamalarda wide event kullanimi yaygindir.

winston'a karsi: evlog, yeni TypeScript projeleri icin daha modern, daha hizli ve daha zengin bir secenek. winston, yasinmis yapisi ve TypeScript desteginin yetersizligi ile gecmiste kaliyor.

consola'ya karsi: consola CLI ortamlarinda guclu bir pretty-print araci. Ama uretime ciktiginizda drain pipeline'i, sampling veya wide event destegi yok. evlog, hem gelistirme ortaminda guzel cikti, hem de uretimde yapilandirilmis JSON sunuyor.

Ama evlog her seyin ustunu cizmiyor. Kabul edilen eksiklikler arasinda, runtime seviye degisimi (pino'daki logger.level = 'debug'), ozel seviyeler (custom levels) ve async I/O worker thread destegi bulunuyor. Bu trade-off'lar, kutuphanenin sade ve odakli kalmasi icin bilerek yapilmis secimler.

Gelecek: AI-Native Observability'nin Temelleri

evlog'un yol haritasi, sadece bir loglama kutuphanesi olmaktan oteye gidiyor. AI SDK entegrasyonu, agent yetenekleri (Cursor, Claude, ChatGPT eklentileri) ve Better Auth entegrasyonu gibi ozellikler, kutuphanenin gozlemlenebilirlik platformuna donusmesinin isaretleri.

FlashQLA'nin edge cihazlarda baslattigi performans devrimini, Mojo 1.0 Beta'nin Python performansini 68.000 kat artirmasiyla bir dusunelim. Bu tur atilimlar, AI uygulamalarinin daha kucuk, daha hizli ve daha dagitik hale gelmesini sagliyor. Ama bu daginiklik, gozlemlenebilirligi de daha da zorlastiriyor. Iste tam bu noktada evlog gibi wide event tabanli, AI-hazir araclar kritik onem kazanıyor.

Yapay zeka ajanlarinin kendi kendine calistigi, binlerce mikro servisin konusmaya basladigi, edge'den buluta veri akan bir dunyada, geleneksel loglama yaklasimlari cokuyor. evlog, bu cokusu ongoren ve cozum sunan nadir acik kaynak projelerden biri.

Sonuc: Log Kazmak Gecmiste Kaldi

evlog'un slogani olan Digging through logs is not observability. It's hope. (Loglari kazmak gozlemlenebilirlik degildir. Umuttur.), modern yazilim gelistirme dunyasinin aci gercegini tanimliyor. Geleneksel loglama, umut etmekten baska bir sey degil. Umarim dogru logu buluruz, umarim korelasyonu kurariz, umarim hatayi cozeriz.

evlog, bu umudu veriye ve yapiya donusturuyor. Wide events ile her istegin tam hikayesini tek bir olayda sunuyor. Structured errors ile hatalari sadece raporlamiyor, ayni zamanda cozum yolunu da gosteriyor. AI SDK entegrasyonu ile LLM cagrilarinin kara kutusunu aydinlatiyor. 13 framework destegi ile ekosistem bagimsizligi sunuyor.

Eger yeni bir TypeScript projesine basliyorsaniz veya mevcut loglama altyapinizi modernize etmeyi dusunuyorsaniz, evlog ciddi sekilde degerlendirilmesi gereken bir secenek. Resmi dokumantasyondaki hizli baslangic rehberi, dakikalar icinde calisan bir ornek kurmanizi sagliyor. GitHub deposu ise MIT lisansli olarak acik. Katkida bulunmak, bug bildirmek veya sadece kodu incelemek tamamen ucretsiz.

Yapay zeka caginda, gozlemlenebilirlik sadece bir opsiyon degil, bir zorunluluk. evlog, bu zorunlulugu en hafif, en hizli ve en yapilandirilmis sekilde yerine getirmenin yollarindan biri. Log kazmaktan vazgecip, olaylari genisletmeye baslamanin zamani geldi.