Node.js İle Winston Kütüphanesi Kullanarak Loglama Sistemi Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Winston ile bir loglama sistemi kurmadan önce bilgisayarınızda Node.js'in güncel bir sürümünün (LTS 20 veya üzeri önerilir) yüklü olması gerekir. Projenizi başlatmak için bir terminal açın ve aşağıdaki adımları izleyin.

Öncelikle projenizi oluşturun ve gerekli kütüphaneyi yükleyin:

# Proje dizinini oluşturun
mkdir node-logger-app
cd node-logger-app

# Projeyi başlatın
npm init -y

# Winston paketini yükleyin
npm install winston

Bu komutlar, projenizin temelini atar ve Winston'ı bağımlılıklar arasına ekler. 2026 yılı standartlarına göre ECMAScript modüllerini (ESM) kullanmanızı öneririz. Bunun için package.json dosyanıza "type": "module" satırını eklemeyi unutmayın.

Winston Loglama Mimarisi ve Temel Yapılandırma

Winston'ın gücü, "Transports" (taşıyıcılar) kavramından gelir. Bir transport, logların nereye gönderileceğini belirler. Örneğin; konsol, bir dosya veya bir veritabanı farklı birer transporttur. İlk adım olarak basit bir yapılandırma dosyası oluşturalım.

logger.js adında bir dosya oluşturun ve temel yapılandırmayı yapın:

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

export default logger;

Yukarıdaki kod, logları hem konsola yansıtır hem de hata mesajlarını error.log, tüm logları ise combined.log dosyasına kaydeder. level: 'info' ayarı, info seviyesindeki ve üzerindeki (warn, error) logların kaydedileceğini belirtir.

Adım Adım Özelleştirilmiş Log Formatları Oluşturma

Varsayılan JSON formatı, makine tarafından okunabilirlik için harikadır ancak yerel geliştirmede okunması zor olabilir. Winston'ın format özelliğini kullanarak loglarınıza zaman damgası (timestamp) ve renkli çıktı ekleyebiliriz.

logger.js dosyanızı aşağıdaki gibi güncelleyerek daha okunabilir bir format tanımlayın:

import winston from 'winston';

const customFormat = winston.format.combine(
  winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
  winston.format.colorize(),
  winston.format.printf(({ timestamp, level, message }) => {
    return `[${timestamp}] ${level}: ${message}`;
  })
);

const logger = winston.createLogger({
  level: 'info',
  format: customFormat,
  transports: [new winston.transports.Console()]
});

export default logger;

Bu yapılandırma, loglarınızı [2026-05-20 14:30:00] info: Uygulama başladı şeklinde daha anlaşılır bir formatta görmenizi sağlar.

Log Seviyeleri ve Kullanım Senaryoları

Winston, RFC5424 standardına uygun log seviyelerini kullanır. Doğru seviyeyi seçmek, sistemin gürültüsünü azaltmak ve hataları hızlıca tespit etmek için kritiktir.

Uygulamanızda bu seviyeleri şu şekilde çağırabilirsiniz:

import logger from './logger.js';

logger.info('Sunucu 3000 portunda başlatıldı.');
logger.warn('Bellek kullanımı %80 seviyesine ulaştı.');
logger.error('Veritabanı bağlantısı zaman aşımına uğradı!');

Üretim Ortamı İçin Log Yönetimi ve Güvenlik

Üretim ortamında log dosyalarınız zamanla devasa boyutlara ulaşabilir. Bu durumu yönetmek için winston-daily-rotate-file paketini kullanmak en iyi pratiktir. Ayrıca, loglarınızda kullanıcı şifreleri veya kişisel veriler (PII) gibi hassas bilgilerin asla yer almadığından emin olmalısınız.

Kritik Uyarı: Log dosyalarına asla kullanıcıların açık metin şifrelerini, kredi kartı bilgilerini veya JWT anahtarlarını yazdırmayın. Bu verilerin sızması, sisteminizin güvenliğini tamamen tehlikeye atar.

Log rotasyonu için paketi yükleyin: npm install winston-daily-rotate-file

import winston from 'winston';
import 'winston-daily-rotate-file';

const transport = new winston.transports.DailyRotateFile({
  filename: 'logs/application-%DATE%.log',
  datePattern: 'YYYY-MM-DD',
  zippedArchive: true,
  maxSize: '20m',
  maxFiles: '14d'
});

const logger = winston.createLogger({
  transports: [transport]
});

Bu yapılandırma, her gün yeni bir dosya oluşturur, 20MB'ı geçen dosyaları sıkıştırır ve 14 günden eski logları otomatik olarak siler.

Sıkça Sorulan Sorular

Loglarımı neden veritabanına değil de dosyaya yazmalıyım?

Logları dosyaya yazmak, uygulamanın performansını etkilemez ve veritabanı çöktüğünde bile loglara erişebilmenizi sağlar. Ancak büyük ölçekli sistemlerde ELK (Elasticsearch, Logstash, Kibana) gibi merkezi log toplama araçları tercih edilmelidir.

Winston performans kaybına yol açar mı?

Winston oldukça optimize edilmiştir. Ancak çok yoğun loglama yapılan sistemlerde, log yazma işlemini "asenkron" modda veya bir kuyruk yapısı (queue) üzerinden yönetmek performansı artıracaktır.

Geliştirme ve üretim ortamı için farklı log seviyelerini nasıl ayarlarım?

process.env.NODE_ENV değişkenini kullanarak, geliştirme ortamında 'debug' seviyesini, üretim ortamında ise 'info' veya 'error' seviyesini aktif edebilirsiniz.

Logları nasıl filtreleyebilirim?

Winston'ın format.metadata veya format.label özelliklerini kullanarak loglara etiket ekleyebilir ve bu etiketlere göre filtreleme yapabilirsiniz.

Winston ile hata takibi nasıl yapılır?

Hata nesnelerini doğrudan loga geçirmek yerine logger.error('Hata mesajı', { error: err }) şeklinde bir nesne olarak geçirmek, hatanın stack trace (yığın izi) bilgisini korumanızı sağlar.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Canlı sistemlerde loglama stratejinizi, şirketinizin veri gizlilik politikalarına ve yasal düzenlemelere (KVKK/GDPR) uygun şekilde yapılandırmanız gerekmektedir.

Winston Loglarını Merkezi Sistemlere (ELK/Logstash) Aktarma

Uygulamanız büyüdükçe, yerel dosya sisteminde tutulan logları tek tek incelemek imkansız hale gelir. Winston'ın en güçlü yanı, logları aynı anda birden fazla hedefe gönderebilmesidir. Loglarınızı merkezi bir sunucuya veya ELK (Elasticsearch, Logstash, Kibana) yığınına aktarmak için winston-logstash-transport gibi kütüphanelerden faydalanabilirsiniz.

Aşağıdaki örnekte, loglarınızı bir TCP soketi üzerinden Logstash'e nasıl gönderebileceğinizi görebilirsiniz:

const winston = require('winston');
require('winston-logstash-transport');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.LogstashTransport({
      port: 5044,
      host: 'logstash.sunucu.adresiniz',
      ssl_enable: true
    })
  ]
});

logger.info('Bu log merkezi ELK sistemine iletildi.');

Loglama Stratejisinde İleri Seviye İpuçları ve Performans Optimizasyonu

Yüksek trafikli Node.js uygulamalarında loglama işlemleri, I/O operasyonları nedeniyle ana döngüyü (event loop) bloklayabilir. Bu durumu engellemek için "Asenkron Loglama" stratejisini benimsemelisiniz. Winston, varsayılan olarak senkron çalışabilir; bu yüzden büyük ölçekli projelerde winston.createLogger içerisinde handleExceptions ve exitOnError parametrelerini dikkatli yapılandırmalısınız.

Performans İçin Kritik İpuçları:

• Stream Kullanımı: Logları doğrudan dosyaya yazmak yerine stream modüllerini kullanarak disk I/O yükünü dağıtın.
• Buffer Boyutu: Logları anlık olarak değil, belirli bir buffer dolduğunda yazmak için winston-daily-rotate-file içindeki maxFiles ve maxSize ayarlarını optimize edin.
• Contextual Logging: Her log satırına request-id ekleyerek, dağıtık sistemlerde bir isteğin tüm yaşam döngüsünü takip edebilirsiniz.

Aşağıdaki kod bloğu, her log satırına otomatik olarak bir correlationId ekleyen özel bir formatlayıcı örneğidir:

const { format } = require('winston');
const { combine, timestamp, json } = format;

const customFormat = combine(
  timestamp(),
  json(),
  format((info) => {
    info.correlationId = global.currentRequestId || 'N/A';
    return info;
  })()
);

const logger = winston.createLogger({
  format: customFormat,
  transports: [new winston.transports.Console()]
});

Bu yöntem, özellikle mikroservis mimarilerinde hata ayıklama (debugging) sürecini %80 oranında hızlandırır. Loglarınızda mutlaka correlationId gibi izlenebilirliği artıran meta veriler bulundurarak, sistemin genel sağlığını daha şeffaf bir şekilde yönetebilirsiniz.

Sonuç

Node.js projelerinizde Winston kullanarak profesyonel bir loglama sistemi kurmak, uygulamanızın izlenebilirliğini artırır ve beklenmedik durumlara karşı hazırlıklı olmanızı sağlar. Bu rehberde öğrendiğiniz transport yönetimi, log rotasyonu ve seviye kullanımı, orta ve büyük ölçekli projelerinizde size büyük kolaylık sağlayacaktır.

Bir sonraki adım olarak, oluşturduğunuz bu loglama sistemini merkezi bir log yönetim servisine (örneğin Datadog, Papertrail veya kendi kuracağınız bir ELK yığını) nasıl bağlayacağınızı araştırmanızı öneririm. Kodunuzu her zaman güncel tutun ve loglarınızı düzenli olarak denetleyerek sisteminizin sağlığını koruyun.