Çıktı, İlerleme ve Çıkış Kodları

GoArchive, bir komutun sonucunu stdout’a, tanılama mesajlarını (diagnostics) stderr’e, tüm günlük kayıtlarını ise logging ayarının belirlediği şekilde günlüğe yazar. İstemediğiniz hiçbir çıktı stdout’a ulaşmaz; hatalar ise her zaman stderr’e yazılır.

Çıktı Akışları #

Üç Günlükleme Düzeni #

• Günlük dosyası (output: <path>): Zamanlanmış çalıştırmalar için önerilen düzendir. --progress olmadan çalıştırma sessizdir: Tamamlandığında veya durduğunda hiçbir şey yazdırmaz; bir hata durumunda ise stderr üzerine bir özet ve hatanın kendisini yazdırır:

  Job archive_old_orders (archive): failed in 61.240s. Log: /var/log/goarchive/orders.log
  Error: engine: …
  

  Başlangıç aşaması tamamlanmadan (bağlantı, ön kontroller, kilitler, kayıt) oluşan bir hatada süre yerine failed before the first batch. ifadesi yer alır. --progress ile başlangıç satırı, ilerleme satırları ve kapanış bloğu stdout’a; günlüğün uyarı ve hataları ise metin satırları olarak stderr’e yazılır. Anlık olaylar günlük seviyesinden bağımsız olarak bunlara eklenir: Replikasyon nedeniyle bekletme (hold), replikanın toparlanması, bir durdurma isteğinin bekletmeyi sonlandırması, duraklatma ve sona ermesi, kurtarma. file_only: true ayarı tüm günlük kayıtlarını konsoldan uzak tutar; uyarılar ve hatalar yine de stderr’e ulaşır.

• Konsolda metin biçiminde günlük (output: stdout veya stderr, format: text): Günlük akışı, renk kodu içermeyen düz metindir. --progress kendi satırlarını ve kapanış bloğunu stdout’a ekler.

• Konsolda JSON biçiminde günlük (output: stdout veya stderr, format: json): Varsayılan düzendir ve konteynerler için önerilir. Günlük akışının her satırı tek bir JSON nesnesidir. --progress satır yazdırmak yerine Run starting, progress ve kapanış kayıtlarını bu akışa yazar; kapanış kaydı sayımları da içerir. output: stdout ayarında bir hata oluşursa stderr’e tek bir düz Error: satırı yazılır; output: stderr ayarında ise hatanın kendisi kapanış kaydıdır. Günlük henüz oluşmadan tespit edilen bir hata (bir parametre, yapılandırma dosyası, bilinmeyen bir görev) her zaman düz bir Error: satırı olarak yazılır.

validate ve dry-run, raporlarını her düzende stdout üzerine metin olarak yazdırır. Konteyner ortamında bu komutlar için logging.output: stderr ayarını kullanın; böylece stdout yalnızca raporu, stderr ise yalnızca günlüğü taşır.

İlerleme Göstergesi #

Değer verilmeden kullanılan --progress her 30 saniyede bir rapor verir. --progress=10s veya --progress=1m30s ile aralığı belirleyebilirsiniz; yalnızca tam sayı verildiğinde değer saniye olarak yorumlanır (en az bir saniye). Değer = işaretiyle bitişik yazılmalıdır: --progress 10s biçimi, doğru yazımı gösteren bir ipucuyla reddedilir.

Job archive_old_orders (archive): starting. Log: /var/log/goarchive/orders.log
progress: roots  4000/~12000 ( 33.3%)  remaining=8000   copied_rows=21640      deleted_rows=21640      elapsed=42s      eta=1m18s
progress: roots  8000/~12000 ( 66.7%)  remaining=4000   copied_rows=43310      deleted_rows=43310      elapsed=1m12s    eta=36s
progress: roots 12000/~12000 (100.0%)  remaining=0      copied_rows=64920      deleted_rows=64920      elapsed=1m49s    eta=0s

• Kolonlar sabit genişliktedir; böylece ardışık satırlar alt alta hizalanır. Günlük konsolda JSON biçiminde yazıldığında her satır bunun yerine bir progress günlük kaydıdır. Bu kayıt roots_done, roots_total, percent, remaining, copied_rows, deleted_rows, elapsed_seconds ve eta alanlarını, duraklatma sırasında ise ek olarak paused alanını taşır.
• Toplam değer bir tahmindir. roots, yüzde, remaining ve tahmini bitiş süresi (ETA) kök kayıtları sayar. ~ ile işaretlenen toplam, sorgu iyileştiricinin (optimizer) where aralığı için yaptığı tahmindir ve kurtarma işleminden sonra bir kez okunur. Hiçbir sayım yapılmadığı için --progress kaynakta ek bir tarama yapmaz. where koşulu bir indeks tarafından karşılandığında tahmin gerçeğe yakındır. where koşulu her satırı bir alt sorgu (subquery) veya fonksiyonla filtrelediğinde ise tahmin her iki yönde de büyük sapma gösterebilir.
• Sınırlar: Yüzde 100’de, remaining ise sıfırda sabitlenir. ETA, ilk kök kayıt tamamlanana kadar calculating, tahmin aşıldığında ise unknown gösterir. Tamamlanan bir çalıştırma, işlenen kayıt sayısını toplam olarak gösterir. dry-run ise aralığı kesin olarak sayar.
• Tahmin okunamazsa çalıştırma ilk yığından önce başarısız olur (engine: --progress estimate on <table>: …). Devam etmek için görevi --progress olmadan çalıştırın.
• Son satır: İlk yığın başladıktan sonra her çıkışta tek bir son satır yazdırılır; doğal olarak sona eren bir çalıştırma remaining=0 gösterir. Başlangıç veya kurtarma aşamasında duran ya da başarısız olan bir çalıştırma hiçbir ilerleme satırı yazdırmaz.

Kapanış Bloğu #

--progress ile başlatılan bir çalıştırma, stdout üzerinde bir kapanış bloğuyla sona erer:

Job archive_old_orders (archive): completed in 109.412s
  roots: 12000 in 12 batches

  table           copied  deleted  verified (sha256)
  orders           12000    12000              12000
  order_items      40920    40920              40920
  order_payments   12480    12480              12480

Durum bilgisi completed, stopped before the end of the where range: run the job again to continue veya failed olur; failed durumunda hata stderr’e yazılır. Kalıcı silme (purge) görevleri deleted, salt kopyalama görevleri ise copied ve verified kolonlarını gösterir; verification: none ayarında verified kolonu yer almaz. Kurtarılan kök kayıtlar, atlanan kök kayıtlar ve kabul edilen değer dönüştürmeleri roots satırının altında listelenir.

Çıkış Kodları #

Hatayla karşılaşan bir durdurma 1 koduyla çıkar. Zamanlanmış bir betikte:

goarchive archive -c archiver.yaml --job archive_old_orders
case $? in
  0|3) ;;                     # tamamlandı veya durduruldu: sonraki çalıştırma devam eder
  4)   exit 0 ;;              # işi başka bir çalıştırma tutuyor: daha sonra tekrar deneyin
  *)   exit 1 ;;              # hata veya hatalı kullanım: stderr çıktısını ve günlüğü inceleyin
esac

Konteynerler #

Varsayılan günlükleme ayarını (stdout’a JSON) koruyun; böylece konteynerin günlük akışı, herhangi bir dosya veya bağlama noktası (mount) gerektirmeden çalıştırmanın tamamını taşır. Ön planda çalışan bir docker run, GoArchive’ın çıkış kodunu döndürür. Arka planda (detached) çalışan bir konteynerde çıkış kodu, docker wait <name> komutunun yazdırdığı sayıdır. docker stop bir SIGTERM sinyali gönderir ve bu bir kontrollü durdurmadır (graceful stop): Durdurma süre sınırı dolmadan önce işlenmekte olan yığın tamamlanırsa çalıştırma 3 koduyla çıkar. Varsayılan süre sınırı 10 saniyedir; bu süre dolduğunda süreç zorla sonlandırılır (kill) ve bir sonraki çalıştırma takip günlüğünde kayıtlı olan işi kurtarır. docker stop --time veya Compose’daki stop_grace_period değerini bir yığının süresinden büyük ayarlayın. İmajın kullanıcısı ve bağlama noktaları için Kurulum sayfasına bakın.