Python Otomasyonlarında Log Tasarımı ve Log Çıktısını Okuma

Python logging, bir otomasyon betiğinin ne yaptığını yalnızca çalıştığı anda görmek için değil, işlem tamamlandıktan sonra geriye dönüp anlayabilmek için kullanılır. İyi tasarlanmış bir log; işlemin ne zaman başladığını, hangi kaynağın kullanıldığını, hangi hedefe yazıldığını, sonucun ne olduğunu ve hata oluştuysa hatanın hangi adımda meydana geldiğini açıkça göstermelidir.

Ekrana rastgele print() mesajları yazdırmak küçük denemelerde yeterli görünebilir; ancak dosya taşıma, CSV işleme veya API çağrısı gibi otomasyonlarda teşhis ve işlem takibi için yetersiz kalır. Log mesajları belirli seviyeler, zaman bilgisi, olay kaynağı ve düzenli bir formatla üretildiğinde hata ayıklama ve sonradan inceleme çok daha kolay hâle gelir.

Python Otomasyonlarında Log Tasarımı Neden Gereklidir?

Bir otomasyon betiğinin başarılı biçimde çalışması, yalnızca beklenen dosyayı üretmesi veya API yanıtı alması anlamına gelmez. Betiğin hangi adımlardan geçtiğini anlayabilmek de önemlidir. Örneğin bir klasördeki dosyaları başka bir klasöre taşıyan betik çalışmış olabilir; fakat hangi dosyaların taşındığı, hangi dosyaların atlandığı ve işlemin nerede durduğu bilinmiyorsa sorun çıktığında elle inceleme yapmak gerekir.

Log tasarımının temel amacı, otomasyonun çalışma akışını anlaşılır olaylara bölmektir. Her olay için “ne oldu?”, “hangi nesne üzerinde oldu?” ve “sonuç neydi?” sorularına mümkün olduğunca cevap verilmelidir. Bu yaklaşım, yalnızca hata mesajı yazmaktan daha değerlidir; çünkü hata genellikle kendisinden önce gerçekleşen işlemlerle birlikte anlam kazanır.

Log ile print arasındaki temel fark nedir?

print() doğrudan bir metni ekrana gönderir. Bu, hızlı denemelerde veya geçici kontrol noktalarında kullanışlıdır. Ancak print() mesajlarının önem seviyesi, kaynağı, standart formatı veya dosyaya yönlendirilmesi kendiliğinden oluşmaz. Mesajları daha sonra filtrelemek, yalnızca hataları ayırmak veya farklı çıktıları aynı anda takip etmek de zorlaşır.

logging modülü ise olayları yapılandırılmış bir akış içinde üretir. Bir mesajın INFO, WARNING veya ERROR seviyesinde olması; okuyucuya olayın normal akışın parçası mı, dikkat gerektiren bir durum mu, yoksa işlemi etkileyen bir hata mı olduğunu anlatır. Mesajın terminale, dosyaya veya her iki hedefe gönderilmesi de yapılandırılabilir.

• Hata teşhisi: Hatanın hangi adımda ve hangi kaynak üzerinde oluştuğu görülebilir.
• İşlem takibi: Betiğin başladığı, hangi nesneleri işlediği ve ne zaman tamamlandığı izlenebilir.
• Sonradan inceleme: Terminal kapandıktan sonra dosyaya yazılan kayıtlar tekrar okunabilir.
• Filtreleme: Yalnızca uyarıları veya hataları incelemek mümkün olur.
• Tutarlı iletişim: Farklı otomasyon betikleri benzer bir mesaj düzeniyle çalışabilir.

Dosya taşıma senaryosunda hangi olaylar loglanmalıdır?

Dosya taşıma otomasyonunda yalnızca “dosya taşındı” mesajı yeterli değildir. Teşhis için kaynak ve hedef yolları, dosyanın işleme uygun olup olmadığı ve işlem sonucu birlikte düşünülmelidir.

• Betiğin dosya tarama işlemine başladığı belirtilmelidir.
• İşlenecek kaynak klasör veya dosya grubu açıkça yazılmalıdır.
• Her dosya için kaynak yol ile hedef yol ilişkilendirilmelidir.
• Hedef klasör bulunamadıysa veya dosya zaten mevcutsa durum açıklanmalıdır.
• Taşıma tamamlandığında işlem sonucu ve mümkünse toplam işlenen dosya sayısı belirtilmelidir.

Örneğin “dosya taşınamadı” ifadesi tek başına yetersizdir. “Kaynak dosya okunamadı”, “hedef klasöre erişilemedi” ve “aynı isimde dosya bulundu” farklı teşhis yolları gerektirir. Log mesajı bu ayrımı kurabildiğinde, sorun doğrudan ilgili adımdan araştırılabilir.

CSV okuma işleminde izlenebilirlik nasıl sağlanır?

CSV işleyen bir betikte dosyanın bulunması, dosyanın açılması, başlık satırının beklenen yapıda olması ve satırların işlenmesi birbirinden farklı olaylardır. Bu nedenle log tasarımı da bu adımları birbirine karıştırmamalıdır.

• Okunacak CSV dosyasının adı veya güvenli biçimde tanımlanmış yolu loglanmalıdır.
• Dosyanın bulunduğu ve okumaya başlandığı belirtilmelidir.
• Beklenen sütunlardan biri eksikse hangi sütunun bulunamadığı açıklanmalıdır.
• Bozuk bir satır atlandıysa satır numarası gibi teşhise yardımcı, hassas olmayan bağlam eklenmelidir.
• İşlem sonunda tüm kayıtların mı, yoksa yalnızca geçerli kayıtların mı işlendiği belirtilmelidir.

Burada amaç CSV içeriğinin tamamını loga dökmek değildir. Özellikle müşteri adı, e-posta adresi, telefon numarası veya başka kişisel veriler içeren dosyalarda yalnızca gerekli teknik bağlam yazılmalıdır. Bir satırdaki sorunu teşhis etmek için çoğu zaman satır numarası, sütun adı ve hata türü yeterlidir.

API isteğinde hangi bilgiler kayda alınmalıdır?

API çağrısı yapan otomasyonlarda loglar, isteğin zamanlamasını ve sonucunu anlamaya yardımcı olur. İsteğin hangi iş adımı için yapıldığı, hangi uç noktaya veya hizmet türüne yöneldiği, yanıtın başarılı olup olmadığı ve hata durumunda hangi sınıfla karşılaşıldığı kaydedilebilir.

• İsteğin başlatıldığı belirtilmelidir.
• Gerekirse hassas olmayan bir işlem adı veya kaynak tanımı eklenmelidir.
• Yanıtın başarılı, beklenmeyen veya hatalı olduğu ayrıştırılmalıdır.
• Zaman aşımı, bağlantı sorunu veya geçersiz yanıt gibi hata türleri açıkça yazılmalıdır.
• Parola, erişim anahtarı, yetkilendirme başlığı ve kişisel veri loglanmamalıdır.

Bir API isteğinde tüm yanıt gövdesini loglamak çoğu zaman doğru yaklaşım değildir. Yanıtın içinde kişisel bilgiler veya erişim bilgileri bulunabilir. Bunun yerine işlem kimliği gibi güvenli bir referans, yanıtın genel durumu ve teknik hata sınıfı kullanılabilir.

Otomasyon mantığını adım adım kurarken olayları nasıl adlandıracağınızı ve hangi bilgilerin gerçekten gerekli olduğunu Python ve yazılım geliştirme üzerine uygulamalı içeriklerde örneklerle karşılaştırabilirsiniz. Buradaki amaç daha fazla mesaj yazmak değil, doğru mesajı doğru noktada üretmektir.

Python logging Modülünün Temel Yapısı: Logger, Seviye, Handler ve Format

Python logging modülünü anlamanın en kolay yolu onu dört parçaya ayırmaktır: logger, seviye, handler ve format. Logger olayın kaynağını temsil eder; seviye olayın önem derecesini belirler; handler çıktının nereye gideceğini seçer; format ise mesajın hangi alanlarla gösterileceğini düzenler.

Logger olayın kaynağını nasıl temsil eder?

Logger, betiğin hangi bölümünden bir olay üretildiğini anlamaya yarar. Büyük bir otomasyonda dosya okuma, dosya taşıma ve API çağrısı gibi farklı işler bulunabilir. Her olayın yalnızca metin olarak değil, anlamlı bir logger adıyla ilişkilendirilmesi, kayıtları sonradan ayırmayı kolaylaştırır.

Örneğin dosya_tasima, csv_isleme veya api_aktarim gibi adlar, aynı uygulamadaki farklı görevleri birbirinden ayırabilir. Başlangıç seviyesinde tek bir logger ile çalışmak yeterli olabilir; ancak logger adının anlamlı seçilmesi, betik büyüdüğünde önemli bir düzen avantajı sağlar.

Seviye ile handler arasındaki ilişki neden önemlidir?

Seviye, bir olayın önemini anlatır; ancak bir mesajın gerçekten gösterilip gösterilmeyeceği logger ve handler seviyelerine bağlıdır. Logger belirli bir eşik altında kalan mesajları işleme almayabilir. Handler da kendisine ulaşan kayıtlar içinden yalnızca belirlediği seviyeye uygun olanları yazabilir. Bu yüzden logger seviyesini düşük tutup handler seviyesini farklı belirlemek, terminal ve dosya çıktısını ayırmak için kullanılabilir.

Örneğin terminalde yalnızca WARNING ve ERROR mesajlarını görmek, fakat dosyada INFO kayıtlarını da saklamak isteyebilirsiniz. Böyle bir tasarımda iki ayrı handler kullanılır ve her handler için uygun seviye seçilir. Aksi durumda beklediğiniz mesajlar terminalde görünmeyebilir veya gereğinden fazla ayrıntı aynı hedefe yazılabilir.

Handler çıktıyı terminale ve dosyaya nasıl yönlendirir?

Handler, log kaydının gideceği hedefi belirler. Terminal çıktısı için akış tabanlı bir handler, dosya kaydı için dosya tabanlı bir handler kullanılabilir. Aynı logger’a birden fazla handler eklenirse tek bir olay hem terminale hem de log dosyasına gönderilebilir.

Aşağıdaki kısa örnek, klasördeki dosyaları tararken normal akışı terminale ve dosyaya yazacak temel bir yapı gösterir:

import logging
from pathlib import Path

logger = logging.getLogger("dosya_tasima")
logger.setLevel(logging.INFO)
formatlayici = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
terminal = logging.StreamHandler()
dosya = logging.FileHandler("otomasyon.log", encoding="utf-8")
terminal.setFormatter(formatlayici)
dosya.setFormatter(formatlayici)
logger.addHandler(terminal)
logger.addHandler(dosya)

for dosya_yolu in Path("gelen").glob("*"):
    logger.info("İşleniyor: %s", dosya_yolu.name)

Bu örnekte logger olayın kaynağını, INFO seviyesi normal işlem akışını, iki handler ise çıktı hedeflerini temsil eder. Formatter zaman bilgisini, önem seviyesini ve mesajı aynı düzen içinde yazar. Python’un resmî logging modülü dokümantasyonu, logger seviyeleri, handler eşikleri ve formatter kullanımının bu temel ilişkisini açıklar.

Gerçek bir betikte aynı handler’ın birden fazla kez eklenmemesine de dikkat edilmelidir. Yapılandırma fonksiyonu birden fazla çalıştırılırsa aynı olay iki veya daha fazla kez yazılabilir. Bu nedenle logging kurulumu genellikle betiğin başlangıcında bir kez yapılmalı, logger ve handler sorumlulukları birbirine karıştırılmamalıdır.

Bu dört kavramı yalnızca tanım olarak değil, dosya işleme ve hata ayıklama adımlarıyla birlikte çalışmak isteyenler için birebir Python dersleri kapsamında da uygulamalı biçimde ele alınabilir. Öğrenme sırasında önemli olan, her log satırının hangi soruya cevap verdiğini görebilmektir.

Temel logger yapılandırmasında kontrol listesi

• Logger adı, yaptığı işlemi anlaşılır biçimde temsil ediyor mu?
• Normal akış mesajları ile hata mesajları farklı seviyelerde mi?
• Terminal ve dosya için ayrı handler gerekip gerekmediği belirlendi mi?
• Format içinde zaman, seviye ve mesajı ayırt etmeye yarayan alanlar var mı?
• Dosya yolu, kişisel veri veya erişim bilgisi gereksiz biçimde loglanıyor mu?
• Logging yapılandırmasının birden fazla kez çalışıp aynı kaydı çoğaltma ihtimali var mı?

INFO, WARNING ve ERROR Seviyeleri Ne Zaman Kullanılır?

Python otomasyonlarında log seviyesini seçerken temel soru şudur: İşlem beklenen şekilde mi ilerliyor, yoksa dikkat gerektiren bir durum mu oluştu? Normal akışı bildiren olaylar için INFO, işlemi tamamen durdurmayan beklenmedik durumlar için WARNING, bir işlevin yerine getirilemediği durumlar için ise ERROR kullanılmalıdır.

Python belgelerinde INFO beklenen çalışmanın doğrulanması, WARNING beklenmeyen ancak uygulamanın çalışmaya devam ettiği durumlar, ERROR ise belirli bir işlevin gerçekleştirilemediği daha ciddi problemler için tanımlanır. Varsayılan yapılandırmada WARNING ve üzerindeki seviyeler görünür; bu nedenle otomasyonun normal akışını izlemek istiyorsanız logger seviyesini ayrıca INFO olarak yapılandırmanız gerekir. Ayrıntılı tanımlar için Python logging dokümantasyonu incelenebilir.

INFO: Normal akışı ve başarılı adımları gösterir

INFO, otomasyonun beklenen işi yaptığını gösterir. Bir dosya taşıma betiği çalışmaya başladığında, kaç dosya bulunduğunda, hangi klasörün kaynak ve hangisinin hedef olduğunda ya da tek bir dosya başarıyla taşındığında bu seviye uygundur.

Örneğin bir CSV arşivleme işleminde aşağıdaki olaylar INFO seviyesinde kaydedilebilir:

• İşlemin başladığı bilgisi
• Kaynak klasör ve hedef klasör
• İşlenecek dosya sayısı
• Bir dosyanın başarıyla okunduğu
• Bir dosyanın hedef klasöre taşındığı
• API isteğinin başarıyla tamamlandığı
• İşlemin tamamlandığı

Burada amaç her satırı ayrıntılı biçimde yazmak değil, bir çalıştırmanın beklenen akışını sonradan takip edebilmektir. Örneğin:

INFO | işlem başladı | kaynak=./gelen | hedef=./arsiv
INFO | dosya sayısı | adet=12
INFO | dosya taşındı | kaynak=fatura_01.csv | hedef=arsiv/fatura_01.csv
INFO | işlem tamamlandı | durum=başarılı

Bu kayıtlar, dosyanın neden taşınmadığını açıklamaz; ancak işlemin gerçekten başlayıp başlamadığını, doğru klasörlerin kullanılıp kullanılmadığını ve başarılı adımların nerede gerçekleştiğini gösterir.

WARNING: İşlem sürerken dikkat gerektiren durumlar

WARNING, otomasyonun tamamen durmadığı fakat normal akıştan sapıldığı durumlarda kullanılır. Uyarı sonrasında betik kalan dosyaları işlemeye devam edebiliyorsa bu seviye genellikle daha doğru seçimdir.

Dosya işleme senaryosunda şu örnekler WARNING seviyesine uygundur:

• Desteklenmeyen uzantıya sahip bir dosyanın atlanması
• İsteğe bağlı bir CSV sütununun bulunmaması ancak temel sütunların mevcut olması
• Boş bir klasörle karşılaşılması
• Dosyanın daha önce arşivlenmiş olması nedeniyle yeniden işlenmemesi
• Bir API yanıtında beklenen isteğe bağlı alanın bulunmaması
• Dosya adının kurum içi isimlendirme kuralına uymaması fakat dosyanın güvenle atlanabilmesi

Örneğin klasörde .txt, .csv ve .tmp dosyaları varsa, yalnızca CSV dosyaları işleniyorsa geçici dosyanın atlanması işlemi durdurmadığı için uyarı olarak kaydedilebilir:

WARNING | dosya atlandı | kaynak=./gelen/notlar.tmp
WARNING | neden=desteklenmeyen uzantı | uzantı=.tmp

Ancak burada önemli bir ayrım vardır: Atlanan dosya iş sürecinin zorunlu girdisiyse olay artık yalnızca bir uyarı olmayabilir. Örneğin günlük raporun oluşturulması için zorunlu olan satışlar.csv bulunamıyorsa işlem devam etse bile sonuç güvenilir olmayabilir. Seviye seçimi, olayın adından çok otomasyonun iş sonucuna etkisine göre yapılmalıdır.

ERROR: Beklenen işlev gerçekleştirilemediğinde kullanılır

ERROR, programın belirli bir işi yapamadığını anlatır. Bu, her zaman tüm programın durduğu anlamına gelmez. Bir dosya taşınamasa bile betik diğer dosyaları işlemeye devam edebilir; yine de başarısız taşıma işlemi ERROR olarak kaydedilmelidir.

Dosya, CSV ve API otomasyonlarında tipik ERROR örnekleri şunlardır:

• Kaynak dosyanın işlem sırasında silinmesi veya bulunamaması
• Dosyanın hedef klasöre taşınamaması
• CSV dosyasının bozuk olması veya okunamaması
• Gerekli bir sütunun eksik olması ve işleme devam edilememesi
• API çağrısının başarısız olması
• İstek zaman aşımına uğradığı için verinin alınamaması
• Hedef klasöre yazma izni bulunmaması

Bir dosya taşınamadığında yalnızca ERROR | hata oluştu yazmak teşhis için yetersizdir. En azından kaynak, hedef ve hata türü birlikte tutulmalıdır:

ERROR | dosya taşınamadı
kaynak=./gelen/rapor.csv
hedef=./arsiv/rapor.csv
hata_türü=FileNotFoundError

Hata yakalama bloğunda logger.exception() kullanılması, hata seviyesinde kayıt üretirken istisnanın bağlamını ve traceback bilgisini korumaya yardımcı olur. Böylece yalnızca hatanın sınıfını değil, hatanın kod içinde hangi satırda ortaya çıktığını da incelemek mümkün olur. Bu yaklaşım yalnızca bir istisna yakalama bloğu içinde kullanılmalıdır.

Aynı olay yanlış seviyede nasıl loglanır?

Bir dosyanın taşınamaması, normal akışın parçası değildir. Bu nedenle aşağıdaki kullanım yanıltıcıdır:

logger.info("dosya taşınamadı | kaynak=%s", kaynak)

Bu kayıt, dosya taşınamamasını başarılı ve beklenen bir işlem gibi gösterir. Özellikle yalnızca ERROR kayıtlarını filtreleyen bir incelemede sorun görünmez.

Daha doğru kullanım şöyledir:

try:
    shutil.move(kaynak, hedef)
    logger.info("dosya taşındı | kaynak=%s | hedef=%s", kaynak, hedef)
except OSError:
    logger.exception(
        "dosya taşınamadı | kaynak=%s | hedef=%s",
        kaynak,
        hedef
    )

Ters yönde de hata yapılabilir. Desteklenmeyen bir dosyanın bilinçli olarak atlanmasını ERROR seviyesinde kaydetmek, gerçek hataları uyarı ve önemsiz olayların arasında görünmez hâle getirebilir:

logger.error("tmp dosyası işlenmedi")

Bu olay işlem sonucunu etkilemiyorsa şu kullanım daha anlamlıdır:

logger.warning(
    "dosya atlandı | kaynak=%s | neden=desteklenmeyen uzantı",
    kaynak
)

Minimal log şeması nasıl oluşturulur?

Bir otomasyon logunun teşhis edilebilir olması için her satırda bütün uygulama ayrıntılarını taşımak gerekmez. Bunun yerine tekrar tekrar ihtiyaç duyacağınız temel alanları tutarlı biçimde kaydetmek daha yararlıdır. Dosya taşıma, CSV işleme ve API çağrıları için kullanılabilecek minimal şema aşağıdaki gibidir.

Şemadaki “işlem başlangıcı” alanı pratikte bir zaman damgası olarak tutulur. “Kaynak” ve “hedef” bilgileri, özellikle aynı ada sahip dosyaların farklı klasörlerde bulunduğu otomasyonlarda kritik önem taşır. “Durum” alanı başarılı ve başarısız akışları ayırırken, “hata türü” sorunun nedenini daraltır. “İşlem süresi” ise yalnızca gerçekten ölçüldüğünde yazılmalıdır; örnek loglarda ölçülmemiş bir süreyi gerçek sonuç gibi göstermek doğru değildir.

Seviyeleri belirlerken şu kısa karar çerçevesi kullanılabilir:

1. Olay beklenen akışın bir parçası mı? Evetse INFO kullanın.
2. Beklenmeyen bir durum var ama otomasyon güvenli biçimde devam ediyor mu? WARNING kullanın.
3. Belirli bir işlev yerine getirilemedi mi? ERROR kullanın.
4. Olayı sonradan bulmak için kaynak, hedef ve hata türü yeterince açık mı kontrol edin.
5. İşlem süresi yazılacaksa gerçekten ölçüldüğünden emin olun.

Çalışan Bir Dosya İşleme Örneğinde Log Çıktısı Nasıl Okunur?

Aşağıdaki örnek, kaynak klasöründeki dosyaları hedef klasörüne taşır. Logger aynı mesajı hem terminale hem de dosya_tasima.log dosyasına yazar. Format içinde zaman damgası, seviye, logger adı ve mesaj bulunduğu için çıktı hem ekranda okunabilir hem de daha sonra dosya üzerinden incelenebilir.

from pathlib import Path
import logging
import shutil

kaynak = Path("kaynak")
hedef = Path("hedef")
hedef.mkdir(exist_ok=True)

logger = logging.getLogger("dosya_tasima")
logger.setLevel(logging.INFO)
formatlayici = logging.Formatter("%(asctime)s | %(levelname)s | %(name)s | %(message)s")
terminal = logging.StreamHandler()
dosya = logging.FileHandler("dosya_tasima.log", encoding="utf-8")
terminal.setFormatter(formatlayici)
dosya.setFormatter(formatlayici)
logger.addHandler(terminal)
logger.addHandler(dosya)

logger.info("işlem başladı | kaynak=%s | hedef=%s", kaynak, hedef)
for dosya_yolu in kaynak.glob("*"):
    if not dosya_yolu.is_file():
        continue
    hedef_yolu = hedef / dosya_yolu.name
    try:
        shutil.move(str(dosya_yolu), str(hedef_yolu))
        logger.info("taşındı | kaynak=%s | hedef=%s | durum=başarılı", dosya_yolu, hedef_yolu)
    except (OSError, shutil.Error):
        logger.exception("taşınamadı | kaynak=%s | hedef=%s | durum=başarısız", dosya_yolu, hedef_yolu)

Örneği denemek için Python dosyasının bulunduğu klasörde kaynak adında bir klasör oluşturup içine herhangi bir dosya koyabilirsiniz. Hedef klasörü betik oluşturur. Dosya taşıma sırasında kaynak dosya silinirse, yolu değişirse veya işletim sistemi taşıma işlemine izin vermezse hata bloğu çalışır.

Başarılı taşıma logu nasıl görünür?

Bir dosyanın başarıyla taşındığı varsayımsal çıktı aşağıdaki gibi olabilir:

2026-08-29 14:20:05,412 | INFO | dosya_tasima | işlem başladı | kaynak=kaynak | hedef=hedef
2026-08-29 14:20:05,413 | INFO | dosya_tasima | taşındı | kaynak=kaynak/rapor.csv | hedef=hedef/rapor.csv | durum=başarılı

Bu çıktıyı okurken önce zaman damgasına bakılır. İlk kayıt işlemin başladığı anı, ikinci kayıt ise dosyanın taşınma adımını gösterir. Her iki satırdaki INFO seviyesi normal akışın sürdüğünü belirtir. Kaynak ve hedef alanları birlikte okunduğunda kaynak/rapor.csv dosyasının hedef/rapor.csv konumuna taşındığı anlaşılır.

durum=başarılı ifadesi, taşıma çağrısının hata üretmeden tamamlandığını belirtir. Buradaki log, dosyanın içeriğinin doğru olduğu veya sonraki bir sistem tarafından kabul edildiği anlamına gelmez; yalnızca bu örnekteki taşıma adımının başarılı olduğunu gösterir. Log kaydının kapsamını olduğundan geniş yorumlamamak gerekir.

Başarısız taşıma logu nasıl görünür?

Kaynak dosya işlem başlamadan önce silinmişse ya da taşıma sırasında erişilemez hâle gelmişse beklenen çıktı şu yapıda olabilir:

2026-08-29 14:21:18,027 | INFO | dosya_tasima | işlem başladı | kaynak=kaynak | hedef=hedef
2026-08-29 14:21:18,029 | ERROR | dosya_tasima | taşınamadı | kaynak=kaynak/rapor.csv | hedef=hedef/rapor.csv | durum=başarısız
Traceback (most recent call last):
  ...
FileNotFoundError: [Errno 2] No such file or directory: 'kaynak/rapor.csv'

Burada ilk satır işlemin başlatıldığını, ikinci satır ise belirli bir dosyanın taşınamadığını gösterir. ERROR seviyesi, otomasyonun en az bir işlevi yerine getiremediğini bildirir. Sonraki traceback bölümündeki FileNotFoundError ise ilk inceleme yönünü belirler: kaynak dosya gerçekten var mıydı, dosya adı doğru muydu, başka bir süreç dosyayı taşıdı mı veya betik beklenmeyen bir çalışma klasöründen mi başlatıldı?

Log çıktısını adım adım okuma yöntemi

1. Zaman damgasını bulun. Olayın ne zaman gerçekleştiğini belirleyin. Aynı çalıştırmaya ait kayıtları sıraya koymak için zaman bilgisini kullanın.
2. Seviyeyi ayırın. INFO normal akışı, WARNING dikkat gerektiren ama devam edilebilir durumu, ERROR ise başarısız işlevi gösterir.
3. İşlem adını kontrol edin. Bu örnekte dosya_tasima logger adı, kaydın hangi işlemden geldiğini belirtir.
4. Kaynak-hedef ilişkisini izleyin. Hatanın hangi dosyada ve hangi hedef konuma yönelik oluştuğunu karşılaştırın.
5. Durum alanını okuyun. başarılı veya başarısız bilgisi olayın sonucunu hızlıca özetler.
6. Hata türünü yorumlayın. FileNotFoundError, PermissionError veya başka bir istisna adı, teşhisi farklı yöne taşır.
7. Aynı bağlamdaki kayıtları gruplayın. Kaynak dosya yolu, hedef yolu ve işlem adı birlikte değerlendirilerek yalnızca başarısız dosyaya odaklanın.

Örneğin klasörde 20 dosya bulunmasına rağmen yalnızca bir dosya için ERROR kaydı varsa, ilk adım tüm betiği başarısız kabul etmek değil, ilgili kaynak ve hedef çiftini incelemektir. Buna karşılık işlem başlangıcı logu hiç yoksa sorun dosya taşıma adımından önce, örneğin yanlış çalışma klasörü, yapılandırma veya betiğin hiç başlatılmaması aşamasında olabilir.

Benzer okuma yöntemi CSV ve API otomasyonlarına da uygulanabilir. CSV işleminde kaynak dosya adı, hedef çıktı dosyası, işlem durumu ve hata türü birlikte okunur. API çağrısında ise kaynak bir URL veya uç nokta olabilir; erişim anahtarı, parola ya da kişisel veri loga yazılmadan isteğin hangi işlem için yapıldığı ve başarısızlığın genel türü belirtilmelidir.

Log çıktısı bir hata mesajı koleksiyonu değil, işlem akışının kısa bir izidir. İyi bir kayıt; ne zaman, hangi işlemde, hangi kaynakla, hangi hedef için ne olduğunu ve sonucunun neye dönüştüğünü anlaşılır biçimde gösterir. Bu nedenle başarı kayıtları yalnızca “tamamlandı”, hata kayıtları da yalnızca “hata oluştu” seviyesinde bırakılmamalıdır.

Başarısız İşlemde Bağlamı Korumak ve Güvenli Loglama Kontrolü

Başarısız bir otomasyonda yalnızca “işlem başarısız oldu” yazmak teşhis için yeterli değildir. Genel akış logu, programın ne yaptığını ve hangi aşamada bulunduğunu gösterir; hata logu ise istisnanın türünü, etkilenen dosya veya işlemi ve sorunu anlamaya yetecek bağlamı taşımalıdır. Amaç, hatayı yeniden oluşturmayı kolaylaştırmak; bunu yaparken parola, erişim anahtarı veya gereksiz kişisel verileri loglamamaktır.

Genel akış logu ile hata logu arasındaki fark

Genel akış logları otomasyonun ilerleyişini takip eder. Örneğin bir dosya taşıma betiğinde kaynak klasörün taranmaya başladığını, kaç dosya bulunduğunu ve belirli bir dosyanın işlenmek üzere seçildiğini belirtebilir. Bu kayıtlar, programın hangi adımda olduğunu anlamaya yardımcı olur.

Hata günlüğü ise işlem beklenen şekilde tamamlanmadığında daha açıklayıcı olmalıdır. Bir dosya taşınamadığında hata kaydı mümkünse şu bilgileri içermelidir:

• İşlemin türü: taşıma, kopyalama, okuma, CSV ayrıştırma veya API isteği gibi.
• Etkilenen dosyanın veya kaynağın anlaşılır bir tanımı.
• Varsa hedef klasör ya da hedef sistem.
• İstisnanın türü: örneğin FileNotFoundError, PermissionError veya ValueError.
• Hatanın oluştuğu aşama.
• Teşhis için gerçekten gerekli olan ek bağlam.

Buradaki “bağlam” kavramı, hatayı anlamaya katkı sağlayan bilgileri ifade eder. Dosyanın tam içeriğini, API yanıtındaki bütün alanları veya kullanıcının kişisel bilgilerini loglamak bağlam sağlamakla aynı şey değildir. Çoğu durumda dosya adı, işlem türü ve istisna sınıfı yeterli bir başlangıç sunar.

Hata mesajına yalnızca gerekli bilgiyi ekleyin

Bir hata mesajı, sorunu teşhis etmeye yardımcı olacak kadar açık; gereksiz ayrıntıları dışarıda bırakacak kadar sınırlı olmalıdır. Örneğin “dosya işlenemedi” ifadesi fazla belirsizdir. Buna karşılık “CSV dosyası okunamadı: satışlar.csv” ifadesi işlemi ve kaynağı daha iyi açıklar.

Ancak dosya yolları da her zaman zararsız değildir. Bir bilgisayarın tam yolu içinde kullanıcı adı, müşteri adı, şirket içi klasör adı veya başka bir kişisel bilgi bulunabilir. Bu nedenle özellikle paylaşılabilecek veya uzun süre saklanabilecek loglarda tam yolu olduğu gibi yazmak yerine yalnızca gerekli dosya adını ya da kişisel bölümleri maskelenmiş bir yolu kullanmak daha uygun olabilir.

Örneğin aşağıdaki iki yaklaşım arasında önemli bir fark vardır:

• Gereksiz ayrıntı: /Users/ayse.yilmaz/Müşteriler/ABC_Şirketi/2026/rapor.xlsx dosyası açılamadı.
• Daha sınırlı bağlam: rapor.xlsx dosyası okunamadı; işlem: Excel içeriğini aktarma.

İkinci kayıt, problemin hangi dosyayla ve hangi işlemle ilgili olduğunu gösterirken kullanıcı adını ve müşteri klasörünü açığa çıkarmamaya çalışır. Bu yaklaşım her sistem için otomatik bir güvenlik garantisi vermez; logların nerede tutulduğu, kimlerin erişebildiği ve ne kadar süre saklandığı da ayrıca değerlendirilmelidir.

API çağrılarında hassas verileri loglamayın

API kullanan otomasyonlarda hata ayıklama sırasında istek adresini, durum kodunu veya genel işlem adını loglamak yararlı olabilir. Buna karşılık token, parola, API anahtarı, Authorization başlığı ve kişisel veri değerleri log satırına doğrudan yazılmamalıdır.

Bir isteğin başarısız olması durumunda şu tür bir kayıt genellikle daha güvenli bir çerçeve sunar: “Müşteri senkronizasyon API isteği başarısız oldu; durum kodu: 401; işlem: kayıt güncelleme.” Burada teşhis için gerekli olabilecek işlem türü ve yanıt durumu korunur, fakat kimlik doğrulama bilgisi paylaşılmaz.

İstek gövdesi veya yanıt içeriği gerçekten incelenmek zorundaysa hassas alanlar maskelenmelidir. Örneğin email, telefon, adres, kimlik numarası, token ve parola alanları tamamen çıkarılabilir ya da kısmi maskeleme uygulanabilir. Maskeleme yapılırken gerçek sırrın bir bölümünü görünür bırakmanın da risk oluşturabileceği unutulmamalıdır.

Log yazılmadan önce kontrol et

Bir log satırını kaydetmeden önce aşağıdaki kısa kontrol listesi kullanılabilir. Bu liste özellikle dosya taşıma, CSV veya Excel işleme ve API çağrısı yapan küçük otomasyonlarda pratik bir son kontroldür.

• Hassas veri var mı? Parola, token, API anahtarı, Authorization başlığı veya gereksiz kişisel veri log mesajından çıkarıldı mı?
• Kaynak ve hedef anlaşılır mı? Dosya taşıma ya da kopyalama işleminde hangi kaynağın ve hangi hedefin söz konusu olduğu, güvenli sınırlar içinde anlaşılabiliyor mu?
• Seviye doğru mu? Normal akış için INFO, beklenmeyen fakat işlemi tamamen durdurmayan durumlar için WARNING, tamamlanamayan işlem veya istisna için ERROR kullanıldı mı?
• Hata türü ayırt edilebilir mi? Mesaj yalnızca “başarısız” demek yerine mümkünse FileNotFoundError, PermissionError veya ilgili istisna türünü belirtiyor mu?
• Aynı olay gereksiz tekrarlanıyor mu? Bir hata hem alt fonksiyonda hem de her üst katmanda tekrar tekrar loglanarak çıktıyı okunamaz hâle getiriyor mu?
• İşlem yeniden kurulabilir mi? Log satırını okuyan kişi, hangi aşamada, hangi işlem sırasında ve hangi kaynak üzerinde sorun çıktığını anlayabiliyor mu?

Tekrarlayan hata loglarını sınırlayın

Aynı hatanın birden fazla katmanda tekrar yazılması, önemli bilgilerin gürültü içinde kaybolmasına neden olabilir. Örneğin dosya okuma fonksiyonu hatayı ayrıntılı biçimde logluyor; üstteki işlem yöneticisi de aynı istisnayı hiçbir yeni bağlam eklemeden tekrar yazıyorsa iki satır da aynı olayı anlatır.

Daha iyi yaklaşım, hatanın ilk yakalandığı yerde teknik ayrıntıyı korumak ve üst seviyede yalnızca gerçekten yeni bir bağlam eklemektir. Örneğin alt fonksiyon dosyanın okunamadığını ve istisna türünü yazabilir; üst seviye ise “günlük rapor aktarımı tamamlanamadı” diyerek işlemin genel sonucunu belirtebilir. Böylece iki kayıt birbirini tekrar etmek yerine tamamlar.

Python bilgisindeki eksik noktaları görmek isteyenler, konuya ilişkin ücretsiz Python bilgi testi ile temel kavramlarını sınayabilir. Log seviyeleri, istisnalar ve dosya işlemleri arasındaki ilişkiyi fark etmek, hata mesajlarını yalnızca okumaktan daha ileri bir beceridir.

Kapsamı doğru belirleyin

Bu bölümdeki yaklaşım, başlangıç ve orta seviyedeki otomasyonlarda okunabilir ve güvenli log satırları tasarlamaya odaklanır. Merkezi loglama sistemleri, üretim gözlemlenebilirliği, dağıtık uygulamalarda iz sürme ve ayrıntılı performans ölçümü daha geniş mimari kararlar gerektirir. Küçük bir Python betiğinde önce doğru olayları doğru seviyede kaydetmek, ardından hassas verileri dışarıda bırakmak daha sağlam bir başlangıçtır.

Sık Sorulan Sorular

Python loglarında INFO ile print kullanımı arasındaki temel fark nedir?

print() doğrudan ekrana metin yazdırmak için kullanılan basit bir araçtır. logging ise mesajları seviyelere ayırabilir, farklı handler'lar üzerinden terminale veya dosyaya yönlendirebilir ve hata ayıklama sürecinde daha düzenli bir yapı sunar. Küçük bir denemede print() yeterli olabilir; dosya işleyen veya birden fazla aşaması bulunan otomasyonlarda log seviyeleri daha anlamlı takip sağlar.

Bir dosya taşınamadığında ERROR mesajında hangi bilgiler bulunmalıdır?

Mesajda işlemin taşıma olduğu, etkilenen dosyanın güvenli biçimde tanımlandığı, gerekiyorsa hedef klasörün anlaşılır bir şekilde belirtildiği ve istisna türünün ayırt edilebildiği bilgiler bulunmalıdır. Dosya yolunda kişisel bilgi veya kurum içi hassas klasör adı varsa bunlar maskelenmeli ya da yalnızca gerekli dosya adı kullanılmalıdır. Parola ve erişim anahtarı gibi sırlar hata mesajına eklenmemelidir.

Python logging ile aynı anda hem terminale hem dosyaya log yazılabilir mi?

Evet. Bunun için aynı logger'a farklı handler'lar eklenebilir. Bir handler terminal çıktısını, diğer handler ise dosya çıktısını yönetebilir. Her handler için seviye veya format farklılaştırılabilir; örneğin terminalde kısa mesaj gösterilirken dosyada zaman bilgisi ve işlem bağlamı tutulabilir.

Parola ve API anahtarı içeren bilgilerin loglanması nasıl önlenir?

Log mesajı oluşturulmadan önce hassas alanlar çıkarılmalı veya maskelenmelidir. İstek başlıkları, özellikle Authorization alanı, doğrudan loglanmamalıdır. API yanıtları ve form verileri kaydedilecekse parola, token, anahtar, e-posta, telefon ve benzeri alanlar için açık bir filtre uygulanmalıdır. Otomasyonun her durumda güvenli olduğu varsayılmamalı; logların içeriği, erişimi ve saklama biçimi düzenli olarak kontrol edilmelidir.

İyi tasarlanmış bir log, yalnızca hatayı bildirmez; işlemin nerede ve neden aksadığını anlamaya yardımcı olur. En güvenilir başlangıç, gerekli bağlamı korurken gereksiz ve hassas verileri bilinçli biçimde dışarıda bırakmaktır.