Build ve Runtime Logları: Dockup Dağıtımlarında Hata Ayıklama

Build ve runtime logları farklı sorulara yanıt verir. Build logları kaynak kodun bir image'a nasıl dönüştüğünü ve bu işlemin neden başarısız olduğunu açıklar. Runtime logları ise oluşturulan uygulamanın container veya Kubernetes workload'u başladıktan sonra ne yaptığını gösterir.

Yanlış log akışını okumak zaman kaybettirir. Image oluşturulurken eksik olan bir bağımlılık runtime loglarında hiçbir zaman görünmez. Buna karşılık, başarılı bir image başlangıçta çökerse build çıktısı tamamen temiz olabilir.

Build ve runtime logları arasındaki fark nedir?

Akışı seçmek için dağıtım aşamasını kullanın:

Aşama	Tipik durum	Doğru log	Yaygın hatalar
Klonlama	cloning	Build	Repository erişimi, branch
Bağımlılık kurulumu	building	Build	Lockfile, registry, package
Derleme/bundle oluşturma	building	Build	Type hataları, bellek, eksik dosyalar
Image başlatma	deploying	Runtime ve health	Başlatma komutu, port, izinler
Çalışan servis	running	Runtime	Exception'lar, bağımlılık kesintileri
Readiness kapısı	deploying	Runtime ve health yapılandırması	Yanlış path, yavaş başlangıç

En güncel build çıktısını okuyun:

dockup logs production/api --build --json

Çalışan servisin runtime çıktısını okuyun:

dockup logs production/api --json

İlgili olay daha eskiyse daha fazla runtime satırı isteyin:

dockup logs production/api -n 500 --json

JSON yanıtı hedefi ve log türünü belirtir. Bu da bir agent'ın birbiriyle ilgisiz akışları birleştirmesini önlemeye yardımcı olur.

dockup logs --build --follow nasıl çalışır?

Follow modu, mevcut snapshot'ı poll ederek yeni satırları akış halinde iletir:

dockup logs production/api --build -f --json

JSON modunda çıktı NDJSON'dır: her satır ve her batch için bir nesne gönderilir. Bir tüketici her satırı artımlı olarak işleyebilir.

Son batch, build sonucunun tamamlandığını belirtir. Dağıtım başarılı veya başarısız olduğunda komut kendiliğinden durur ve başarısızlık durumunda non-zero çıkış koduyla sonlanır. Bu sayede elle yazılmış bir durum döngüsüne gerek kalmadan agent veya CI job için kullanılabilir.

Runtime follow da benzer şekilde çalışır:

dockup logs production/api -f --json

Her batch restarted alanını içerir. restarted:true olduğunda container yeniden başlatılmış veya tutulan log buffer'ı yenilenmiş demektir. Bu nedenle Dockup, satırları sessizce kaybetmek yerine mevcut snapshot'ın tamamını yeniden gönderir.

Varsayılan polling aralığı 2 saniyedir. Cadence'i değiştirmek için belgelenen --interval seçeneğini yalnızca belirli bir ihtiyaç olduğunda kullanın.

Başarısız bir build nasıl teşhis edilir?

Terminal dağıtım sonucuyla başlayın:

dockup deploy production/api --wait --json

Komut deploy_failed ile sonlandığında build logunu alın ve son cascade mesajını değil, nedensel ilk hatayı bulun.

Yararlı bir sıra şöyledir:

1. Hedefi ve deployment ID'yi doğrulayın.
2. Klonlama, kurulum, derleme veya image aşamasını belirleyin.
3. Yeniden denenemeyen ilk hatayı bulun.
4. Build yöntemini repository'nin amacıyla karşılaştırın.
5. Mümkünse temiz bir clone üzerinden yeniden üretin.
6. Tek ve odaklanmış bir değişiklik yapın.
7. --wait ile yeniden dağıtın.

Yaygın Nixpacks hataları arasında tanınmayan bir project root, eksik lockfile, standart bir start script'inin bulunmaması veya native package gereksinimi yer alır. Yaygın Dockerfile hataları ise yanlış build context, kopyalanmamış bir artifact, kullanılamayan bir base image veya başarısız olan bir RUN talimatıdır.

Nixpacks ve Dockerfile rehberi, build sistemi seçimi için bir karar haritası sunar.

Deterministik bir build hatasını 900 saniyelik timeout'u artırarak düzeltmeye çalışmayın. Timeout değişikliği gerçek anlamda uzun süren bir build'e yardımcı olur; hatayla sonlanan bir komutu düzeltmez.

Runtime çökmesi veya health hatası nasıl teşhis edilir?

Başarılı bir image, trafik aktarılmadan önce yine de başarısız olabilir. Servis durumunu ve runtime çıktısını inceleyin:

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Şunları arayın:

• Process başlatıldıktan hemen sonra sonlanıyor.
• Uygulama yanlış port'a bind ediyor.
• Uygulama tüm interface'ler yerine 127.0.0.1 üzerinde dinliyor.
• Gerekli environment anahtarı eksik.
• Database veya Redis bağlantısı başarısız.
• Dosya izinleri başlangıcı engelliyor.
• Health path başarı göstermeyen bir status döndürüyor.
• Başlangıç, yapılandırılmış retry sayısının izin verdiğinden uzun sürüyor.
• Bir migration başarısız oluyor veya eşzamanlı çalışıyor.

Health yapılandırması incelenebilir veya güncellenebilir:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Bozuk bir release'in geçmesini sağlamak için health kapısını zayıflatmayın. Başlangıcın gerçekten daha fazla zamana ihtiyacı varsa politikayı kanıta dayanarak değiştirin ve readiness durumunu hâlâ doğrulayan bir endpoint bulundurun.

Environment değişiklikleri yeniden dağıtım gerektirir. Eksik bir secret düzeltildiyse yeniden deploy edin ve bekleyin; eski container'ı yeniden başlatmak yeni istenen environment'ı uygulamaz.

Agent'lar çıkış kodunu kaybetmeden NDJSON'ı nasıl ayrıştırmalı?

Bir agent veya script, process durumunu koruyarak her JSON satırını okumalıdır. Orijinal çıkış kodunu pipefail olmadan maskeleyen bir komuta pipe etmekten kaçının.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

pipefail sayesinde tee başarıyla tamamlanmış olsa bile başarısız bir Dockup komutu pipeline'ın non-zero olmasını sağlar.

Bir tüketici her nesneyi bağımsız olarak inceleyebilir:

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Ham NDJSON artifact'ını saklayın. İnsan tarafından okunabilir bir excerpt pull request veya incident için yararlıdır; ancak özgün alanlar restart işaretlerini, durumu ve tamamlanma sinyallerini korur.

Makine arayüzlerine ilişkin genel ilkeler AI agent CLI tasarımı yazısında açıklanır.

Tekrarlanabilir bir dağıtımda hata ayıklama runbook'u nedir?

Şu karar yolunu kullanın:

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Ardından olayı sınıflandırın:

Sınıflandırma	Kanıt	Sonraki işlem
Kaynak/build	Build logunda hata	Repository'yi veya build tanımını düzeltin
Yapılandırma	Eksik/yanlış env veya port	Yapılandırmayı düzeltin ve yeniden dağıtın
Readiness	Uygulama çalışıyor, health başarısız	Endpoint'i veya gerekçelendirilmiş zamanlamayı düzeltin
Runtime bağımlılığı	Connection exception	Database'i/network'ü/credential'ı kontrol edin
Regression	Önceki sürüm çalışıyordu	Bilinen ID'ye rollback yapmayı değerlendirin
Platform belirsizliği	Timeout, terminal durumu yok	Yeniden denemeden önce durumu inceleyin

Yalnızca bilinen bir önceki deployment'ı belirledikten sonra rollback yapın:

dockup rollback <deploymentId> production/api --json

Önce başarısız deployment ID'sini ve logları saklayın. Rollback servis kullanılabilirliğini geri getirir; kök nedeni açıklamaz.

sıfır kesintili dağıtımlar yazısı, başarısız bir readiness kapısının canlı trafiği neden koruyabildiğini açıklar.

Production logları nasıl faydalı hâle getirilir?

Dockup çıktıyı alabilir, ancak log kalitesini uygulama belirler. Timestamp, severity, request veya trace ID'leri, component adı ve güvenli bir hata açıklaması içeren, yapılandırılmış ve tek olaylı kayıtları tercih edin.

Access token'ları, database URL'lerini, password'leri, tam authorization header'larını veya operasyon için gerekli olmayan kişisel verileri asla loglamayın. Dockup yapılandırmasındaki secret masking, rastgele uygulama çıktılarındaki bilgileri redakte etmez.

Güvenli ve teşhis edilebilir başlangıç bilgilerini loglayın:

• Uygulama sürümü veya commit.
• Environment adı.
• Dinlenen port.
• Secret değerleri olmadan etkin feature adları.
• Password yerine database host sınıfı.
• Migration sürümü.
• Health endpoint readiness durumu.

Incident zaman çizelgesi şablonu

Şunları kaydedin:

1. Deployment ID ve kaynak commit.
2. Deploy başlangıç ve terminal timestamp'leri.
3. Nedensel ilk build veya runtime hatası.
4. Health kapısı sonucu.
5. Kurtarma komutu ve deployment ID.
6. Kullanıcı etkisinin görüldüğü zaman aralığı.
7. Takip sorumlusu.

Uptime verileri dakika düzeyinde kullanılabilirlik ve yanıt süresi ekler:

dockup uptime production/api --hours 24 --json

Sonuç, ortalama ve p95 yanıt süresini içerir. Bir dağıtım incident'ını daha uzun süreli bir performans regression'ından ayırmak için bunu build ve runtime loglarıyla birleştirin.

Güncel log flag'leri için Dockup CLI referansını, güvenli uygulama loglama için security best practices yazısını kullanın.

Logları deployment geçmişiyle ilişkilendirin

Bir satır ancak doğru release'e bağlanabildiğinde faydalıdır. Deployment ID'yi, commit hash'i ve başlangıç zamanını log artifact'ının yanında saklayın. İki release birbirine yakın zamanda gerçekleştiğinde yalnızca timestamp'ler yanıltıcı olabilir.

dockup deployments production/api -n 20 --json

Deployment geçmişi hangi kaynağın etkin olduğunu ve hangi release'in terminal duruma ulaştığını gösterir. Bir agent, servis durumu bu commit'in gerçekten dağıtıldığını doğrulamadan runtime exception'ını en son commit'e bağlamamalıdır.

Log kaynaklı secret ifşasından kaçının

Başarısız bir bağlantı, geliştiricileri tam URL'yi yazdırmaya teşvik eder. Bunun yerine protocol'ü, maskelenmiş host'u, database adını ve hata kategorisini loglayın. Token'lar için, kuruluşun bu yönde bir politikası varsa depolamadan önce oluşturulan güvenli bir fingerprint'i loglayın.

Başarısız build artifact'larını ekip dışına paylaşmadan önce inceleyin. Package manager ve Docker çıktıları, Dockup kayıtlı environment secret'larını doğru şekilde maskelemiş olsa bile private repository URL'leri, registry kullanıcı adları veya komut argümanları içerebilir.

Bu sayede build ve runtime logları ortaklaşa teşhis için yeterince güvenli hâle gelir.

Minimum bir kanıt paketi saklayın

Her başarısız release için deployment sonucu JSON'unu, build logunu, ilgili runtime excerpt'ini, servis durumunu ve seçilen kurtarma deployment ID'sini kaydedin. Bu paket rutin kullanım için yeterince küçüktür ve ikinci bir operatörün belirsiz mutation'ları yeniden çalıştırmadan devam edebilmesi için yeterince kapsamlıdır.

Yalnızca yeni build'i değil, düzeltmeyi de doğrulayın

Düzeltilen deployment başarıyla tamamlandıktan sonra başarısız olan request'i veya başlangıç koşulunu tekrarlayın ve runtime çıktısını izleyerek sorunun yinelenip yinelenmediğini kontrol edin. Incident'ı yalnızca özgün belirti ortadan kalktığında, health kapısı geçildiğinde ve beklenen production davranışı gözlemlendiğinde kapatın.

Döngüyü kapatın

Doğrulanmış düzeltmeyi belgeleyin.

Doğrulanabilir bir deployment ile başlayın

Bir test build'ini kasıtlı olarak başarısız olacak şekilde çalıştırın, NDJSON akışını ve çıkış kodunu yakalayın, ardından runbook'un runtime logu yerine build logunu seçtiğini doğrulayın.

app.dockup.ai adresinde ücretsiz başlayın. Free plan aylık $0'dır, başlangıç kredisi olarak $10 içerir ve bir workspace, üç database ve üç deployment desteği sunar.

SSS

Dockup build logları ile runtime logları arasındaki fark nedir?

Build logları klonlama, bağımlılık kurulumu, derleme ve image oluşturma aşamalarını kapsar. Runtime logları başlatılan uygulama container'ını veya pod'larını kapsar.

Dockup build loglarını canlı olarak nasıl takip ederim?

dockup logs komutunu --build ve --follow veya -f ile kullanın. --json ile komut NDJSON batch'leri gönderir ve deployment'ın terminal durumuna ulaşmasıyla sona erer.

Build follow neden non-zero ile sonlanıyor?

Deployment sonucunu korur. Başarısız bir build, başarılı bir log akışı gibi görünmek yerine çağıran shell'in, CI job'ının veya agent task'ının başarısız olmasını sağlamalıdır.

Runtime follow çıktısındaki restarted:true ne anlama gelir?

Container'ın yeniden başlatıldığını veya tutulan buffer'ın yenilendiğini belirtir. Bu nedenle Dockup satırları sessizce kaybetmek yerine mevcut snapshot'ı yeniden gönderir.

Uygulama logları environment secret'ları içermeli mi?

Hayır. Dockup, kayıtlı yapılandırma okumalarını maskeler; ancak uygulamanın yazdırdığı rastgele secret'ları güvenli hâle getiremez. Credential'ları uygulamanın loglama katmanında redakte edin.