Логове за build и runtime: отстраняване на проблеми при Dockup deployments

Build и runtime логовете отговарят на различни въпроси. Build логовете обясняват как source кодът се е превърнал в image и защо този процес е завършил с грешка. Runtime логовете обясняват какво е направило изграденото приложение, след като container-ът или Kubernetes workload-ът е стартирал.

Четенето на грешния stream губи време. Липсваща dependency по време на създаването на image никога няма да се появи в runtime логовете, докато image, който се създава успешно, но се срива при стартиране, може да има напълно чист build output.

Каква е разликата между build и runtime логовете?

Използвайте етапа на deployment, за да изберете правилния stream:

Етап	Типичен статус	Правилен лог	Чести проблеми
Clone	cloning	Build	Достъп до repository, branch
Инсталиране на dependencies	building	Build	Lockfile, registry, package
Compile/bundle	building	Build	Type грешки, памет, липсващи файлове
Стартиране на image	deploying	Runtime и health	Start команда, port, права
Работещ service	running	Runtime	Exceptions, прекъсвания на dependencies
Readiness gate	deploying	Runtime плюс health конфигурация	Грешен path, бавно стартиране

Прочетете последния build output:

dockup logs production/api --build --json

Прочетете runtime output от работещия service:

dockup logs production/api --json

Поискайте повече runtime редове, когато съответното събитие е по-старо:

dockup logs production/api -n 500 --json

JSON отговорът идентифицира target-а и типа на логовете, което помага на agent да не смесва несвързани stream-ове.

Как работи dockup logs --build --follow?

Режимът follow предава новите редове чрез polling на текущия snapshot:

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

В JSON режим output-ът е NDJSON: по един object на ред и на batch. Consumer може да обработва всеки ред поетапно.

Последният batch обозначава крайния резултат от build-а. Командата спира автоматично, когато deployment-ът завърши успешно или с грешка, и връща ненулев exit код при грешка. Това я прави подходяща за agent или CI job без ръчно написан status loop.

Runtime follow работи по аналогичен начин:

dockup logs production/api -f --json

Всеки batch включва restarted. Когато restarted:true, container-ът е рестартиран или запазеният log buffer е започнал отначало, затова Dockup изпраща отново целия текущ snapshot, вместо тихо да пропусне редове.

Интервалът за polling по подразбиране е 2 секунди. Използвайте документирания --interval само когато има конкретна необходимост да промените честотата.

Как диагностицирате неуспешен build?

Започнете с крайния резултат от deployment-а:

dockup deploy production/api --wait --json

Когато командата завърши с deploy_failed, извлечете build лога и намерете първата причинно-следствена грешка, а не последното каскадно съобщение.

Полезна последователност е:

1. Потвърдете target-а и deployment ID.
2. Идентифицирайте етапа clone, install, compile или image.
3. Намерете първата грешка, която не подлежи на retry.
4. Сравнете build метода с предназначението на repository-то.
5. Ако е възможно, възпроизведете проблема от чист clone.
6. Направете една целенасочена промяна.
7. Изпълнете нов deployment с --wait.

Честите Nixpacks проблеми включват неразпознат project root, липсващ lockfile, липсващ конвенционален start script или изискване за native package. Честите проблеми с Dockerfile включват неправилен build context, липсващ копиран artifact, недостъпен base image или неуспешна RUN инструкция.

Ръководството Nixpacks срещу Dockerfile предоставя карта за избор на build система.

Не отстранявайте детерминистична build грешка чрез увеличаване на timeout-а от 900 секунди. Промяната на timeout-а помага при основателно дълъг build; тя не поправя команда, завършила с грешка.

Как диагностицирате runtime crash или health failure?

Успешно създаден image все пак може да се повреди преди пренасочването на трафика. Проверете състоянието на service-а и runtime output-а:

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

Потърсете:

• Process-ът приключва веднага след стартирането.
• Приложението се bind-ва към грешния port.
• Приложението слуша на 127.0.0.1, вместо на всички interfaces.
• Липсва задължителен environment key.
• Връзката към database или Redis е неуспешна.
• File permissions блокират стартирането.
• Health path връща статус, който не показва успех.
• Стартирането отнема повече време от разрешеното от конфигурираните retries.
• Migration е неуспешна или се изпълнява едновременно с друга.

Health конфигурацията може да бъде прегледана или актуализирана:

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

Не отслабвайте health gate-а само за да накарате повреден release да премине. Ако при нормални условия стартирането изисква повече време, променете policy-то въз основа на доказателства и запазете endpoint, който все още доказва readiness.

Промените в environment изискват нов deployment. Ако липсващ secret е поправен, deploy-нете отново и изчакайте; рестартирането на стария container не прилага новата желана environment конфигурация.

Как agent-ите трябва да анализират NDJSON, без да губят exit кода?

Agent или script трябва да прочита всеки JSON ред, като същевременно запази process status-а. Избягвайте pipe към команда, която скрива оригиналния exit code, без pipefail.

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

С pipefail неуспешната Dockup команда запазва ненулев статус за целия pipeline, въпреки че tee е завършила успешно.

Consumer може да преглежда всеки object самостоятелно:

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

Запазете raw NDJSON artifact-а. Четимият за човек excerpt е полезен за pull request или incident, но оригиналните полета запазват маркерите за рестартиране, статуса и сигналите за завършване.

Общите принципи за machine interface са обяснени в AI agent CLI дизайн.

Как изглежда повторяем runbook за отстраняване на проблеми при deployment?

Използвайте следния път за вземане на решение:

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

След това класифицирайте incident-а:

Класификация	Доказателство	Следващо действие
Source/build	Грешка в build log-а	Поправете repository-то или build дефиницията
Configuration	Липсващ/грешен env или port	Коригирайте конфигурацията и deploy-нете отново
Readiness	Приложението работи, но health проверката е неуспешна	Поправете endpoint-а или обосновете timing-а
Runtime dependency	Connection exception	Проверете database/network/credential
Regression	Предишната версия е работила	Обмислете rollback по известен ID
Platform uncertainty	Timeout, липсващ краен статус	Проверете status-а преди нов опит

Правете rollback само след като идентифицирате известен предишен deployment:

dockup rollback <deploymentId> production/api --json

Първо запазете ID-то и логовете на неуспешния deployment. Rollback възстановява достъпността на service-а; той не обяснява първопричината.

Статията за zero-downtime deployments обяснява защо неуспешният readiness gate може да защити live трафика.

Как production логовете да бъдат полезни?

Dockup може да извлича output, но приложението определя качеството на логовете. Предпочитайте structured записи за едно събитие с timestamp, severity, request или trace ID, име на component и безопасно описание на грешката.

Никога не записвайте access token-и, database URL адреси, пароли, пълни authorization headers или лични данни, които не са необходими за operations. Masking-ът на secret-ите в конфигурацията на Dockup не пречиства произволен output от приложението.

Записвайте безопасни и диагностични факти за стартирането:

• Версия на приложението или commit.
• Име на environment-а.
• Listening port.
• Имена на активираните feature-и без secret стойности.
• Клас на database host-а, но не и паролата.
• Версия на migration.
• Readiness на health endpoint-а.

Шаблон за timeline на incident

Запишете:

1. Deployment ID и source commit.
2. Timestamp-ите за началото и края на deployment-а.
3. Първата причинно-следствена build или runtime грешка.
4. Резултата от health gate-а.
5. Recovery командата и deployment ID.
6. Периода на влияние върху потребителите.
7. Отговорника за последващите действия.

Uptime данните добавят availability и response time на ниво минута:

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

Резултатът включва средно време и p95 response time. Комбинирайте го с build и runtime логовете, за да разграничите incident, свързан с deployment, от по-дълга performance regression.

Използвайте Dockup CLI reference за актуалните log flags и security best practices за безопасно application logging.

Свързвайте логовете с deployment history

Един ред е полезен само когато може да бъде свързан с правилния release. Съхранявайте deployment ID, commit hash и start time заедно с log artifact-а. Когато два release-а се случат близо един до друг, само timestamp-ите могат да бъдат подвеждащи.

dockup deployments production/api -n 20 --json

Deployment history установява кой source е бил активен и кой release е достигнал краен status. Agent не трябва да приписва runtime exception на последния commit, преди service status-ът да потвърди, че този commit действително е бил deploy-нат.

Избягвайте изтичането на secret-и чрез логовете

Неуспешната връзка често изкушава developers да отпечатат целия URL. Вместо това записвайте protocol-а, маскирания host, името на database-а и категорията на грешката. За token-и записвайте само безопасен fingerprint, генериран преди съхранението, когато организацията има policy за това.

Преглеждайте artifact-ите от неуспешен build, преди да ги споделите извън екипа. Output-ът от package manager и Docker може да съдържа URL адреси към private repository-та, registry usernames или аргументи на команди, дори когато Dockup правилно маскира съхранените environment secret-и.

Това прави build и runtime логовете достатъчно безопасни за съвместна диагностика.

Запазвайте минимален пакет от доказателства

За всеки неуспешен release запазвайте JSON резултата от deployment-а, build log-а, съответния runtime excerpt, service status-а и избрания recovery deployment ID. Този пакет е достатъчно малък за рутинна употреба и достатъчно пълен, за да може втори оператор да продължи, без да изпълнява повторно несигурни мутации.

Потвърдете поправката, а не само новия build

След като коригираният deployment завърши успешно, повторете неуспешната заявка или условието за стартиране и наблюдавайте runtime output-а за повторна поява. Приключете incident-а едва когато първоначалният симптом липсва, health gate-ът преминава и очакваното production поведение е потвърдено.

Затворете цикъла

Документирайте потвърдената поправка.

Започнете с проверим deployment

Накарайте един тестов build умишлено да завърши с грешка, запишете неговия NDJSON stream и exit code, след което проверете дали runbook-ът избира build log-а вместо runtime log-а.

Започнете безплатно в app.dockup.ai. Free планът струва $0 на месец, включва начални кредити на стойност $10 и поддържа един workspace, три databases и три deployments.

Често задавани въпроси

Каква е разликата между Dockup build логовете и runtime логовете?

Build логовете обхващат clone, инсталирането на dependencies, compilation и създаването на image. Runtime логовете обхващат стартиралия application container или pods.

Как да следя Dockup build логовете в реално време?

Използвайте dockup logs с --build и --follow или -f. С --json командата извежда NDJSON batches и приключва при крайния статус на deployment-а.

Защо build follow завършва с ненулев exit код?

Той запазва резултата от deployment-а. Неуспешният build трябва да направи calling shell-а, CI job-а или agent task-а неуспешен, вместо потокът от логове да изглежда успешен.

Какво означава restarted:true в runtime follow output-а?

Това означава, че container-ът е рестартиран или запазеният buffer е започнал отначало, затова Dockup е извел текущия snapshot повторно, вместо тихо да загуби редове.

Трябва ли application логовете да съдържат environment secret-и?

Не. Dockup маскира прочитанията на съхранената конфигурация, но не може да направи безопасни произволни secret-и, отпечатани от приложението. Пречиствайте credential-ите на нивото на application logging.