Збірка та runtime-логи: налагодження розгортань Dockup

Логи збірки та runtime-логи відповідають на різні запитання. Логи збірки пояснюють, як із вихідного коду було створено image і чому цей процес завершився помилкою. Runtime-логи показують, що робив застосунок після запуску контейнера або Kubernetes workload.

Читання неправильного потоку марнує час. Відсутня залежність під час створення image ніколи не з’явиться в runtime-логах, тоді як успішний image, який завершується з помилкою під час запуску, може мати абсолютно чистий вивід збірки.

У чому різниця між логами збірки та runtime-логами?

Вибирайте потік відповідно до етапу розгортання:

Етап	Типовий статус	Правильний log	Поширені помилки
Клонування	cloning	Build	Доступ до репозиторію, гілка
Встановлення залежностей	building	Build	Lockfile, registry, package
Компіляція/bundle	building	Build	Помилки типів, пам’ять, відсутні файли
Запуск image	deploying	Runtime і health	Команда запуску, порт, права доступу
Запущений сервіс	running	Runtime	Винятки, недоступність залежностей
Перевірка готовності	deploying	Runtime разом із health config	Неправильний path, повільний запуск

Прочитайте останній вивід збірки:

dockup logs production/api --build --json

Прочитайте runtime-вивід запущеного сервісу:

dockup logs production/api --json

Запросіть більше рядків runtime-логів, якщо потрібна подія вже не входить до останнього фрагмента:

dockup logs production/api -n 500 --json

Відповідь JSON визначає target і тип log, що допомагає agent не змішувати непов’язані потоки.

Як працює dockup logs --build --follow?

Режим follow передає нові рядки, опитуючи поточний snapshot:

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

У режимі JSON вивід має формат NDJSON: один об’єкт на рядок і на batch. Споживач може обробляти кожен рядок поступово.

Фінальний batch позначає підсумковий результат збірки. Команда самостійно завершується, коли розгортання успішне або невдале, і повертає ненульовий код виходу в разі помилки. Це робить її придатною для agent або CI job без написаного вручну циклу перевірки статусу.

Runtime follow працює аналогічно:

dockup logs production/api -f --json

Кожен batch містить restarted. Коли restarted:true, контейнер перезапустився або збережений log buffer прокрутився, тому Dockup повторно передає весь поточний snapshot замість того, щоб непомітно пропустити рядки.

Інтервал опитування за замовчуванням становить 2 секунди. Використовуйте задокументований --interval лише за конкретної потреби змінити частоту опитування.

Як діагностувати помилку збірки?

Почніть із підсумкового результату розгортання:

dockup deploy production/api --wait --json

Коли команда завершується зі статусом deploy_failed, отримайте log збірки та знайдіть першу причину помилки, а не останнє каскадне повідомлення.

Корисна послідовність дій:

1. Підтвердьте target і deployment ID.
2. Визначте етап: clone, install, compile або image.
3. Знайдіть першу помилку, яка не підлягає повторній спробі.
4. Порівняйте метод збірки з призначенням репозиторію.
5. За можливості відтворіть проблему з чистого clone.
6. Внесіть одну цілеспрямовану зміну.
7. Повторно виконайте розгортання з --wait.

Поширені помилки Nixpacks включають нерозпізнаний root проєкту, відсутній lockfile, відсутній стандартний start script або потребу в native package. Типові помилки Dockerfile — неправильний build context, відсутній скопійований artifact, недоступний base image або невдала інструкція RUN.

У посібнику Nixpacks vs Dockerfile наведено схему вибору build system.

Не намагайтеся виправити детерміновану помилку збірки збільшенням тайм-ауту з 900 секунд. Зміна тайм-ауту допомагає для справді довгої збірки, але не виправляє команду, яка завершилася помилкою.

Як діагностувати падіння runtime або помилку health check?

Успішний image все одно може не пройти до перемикання трафіку. Перевірте стан сервісу та runtime-вивід:

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

Зверніть увагу на таке:

• Процес завершується одразу після запуску.
• Застосунок прив’язаний до неправильного порту.
• Застосунок слухає 127.0.0.1, а не всі інтерфейси.
• Відсутній обов’язковий environment key.
• Не вдається підключитися до бази даних або Redis.
• Права доступу до файлів блокують запуск.
• Health path повертає статус, що не свідчить про успіх.
• Запуск триває довше, ніж дозволяє налаштована кількість повторних спроб.
• Міграція завершується помилкою або запускається паралельно.

Конфігурацію health можна переглянути або оновити:

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

Не послаблюйте health gate лише для того, щоб пропустити зламаний реліз. Якщо для запуску обґрунтовано потрібно більше часу, змініть policy на основі фактичних даних і збережіть endpoint, який і надалі підтверджує готовність.

Зміни environment потребують повторного розгортання. Якщо відсутній secret було додано, виконайте deploy ще раз і дочекайтеся його завершення; перезапуск старого контейнера не застосовує нове бажане environment.

Як agent має розбирати NDJSON, не втрачаючи код виходу?

Agent або script має читати кожен JSON-рядок, зберігаючи статус процесу. Не передавайте вивід через команду, яка приховує початковий код виходу, якщо не використовуєте pipefail.

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

Завдяки pipefail невдала команда Dockup залишає pipeline ненульовим, навіть якщо tee успішно завершила роботу.

Споживач може перевіряти кожен об’єкт окремо:

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

Зберігайте необроблений NDJSON artifact. Фрагмент, зручний для читання людиною, корисний для pull request або incident, але оригінальні поля зберігають маркери перезапуску, статус і сигнали завершення.

Загальні принципи machine interface пояснено в матеріалі AI agent CLI design.

Який вигляд має повторюваний runbook для налагодження розгортань?

Скористайтеся таким шляхом прийняття рішення:

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	Виправте репозиторій або build definition
Configuration	Відсутній/неправильний env або порт	Виправте конфігурацію та виконайте redeploy
Readiness	Застосунок працює, але health check не проходить	Виправте endpoint або обґрунтуйте час запуску
Runtime dependency	Виняток під час підключення	Перевірте базу даних, мережу та credential
Regression	Попередня версія працювала	Розгляньте rollback за відомим ID
Platform uncertainty	Тайм-аут, відсутній фінальний статус	Перевірте status перед повторною спробою

Виконуйте rollback лише після визначення відомого попереднього deployment:

dockup rollback <deploymentId> production/api --json

Спочатку збережіть ID невдалого deployment і logs. Rollback відновлює доступність сервісу, але не пояснює першопричину.

У статті zero-downtime deployments пояснено, чому невдалий readiness gate може захистити робочий трафік.

Як зробити production-логи корисними?

Dockup може отримувати вивід, але якість логів визначає застосунок. Надавайте перевагу структурованим записам про одну подію з timestamp, severity, request або trace ID, назвою компонента та безпечним описом помилки.

Ніколи не записуйте access token, URL бази даних, паролі, повні authorization header або персональні дані, які не потрібні для роботи системи. Маскування secret у конфігурації Dockup не приховує довільний вивід застосунку.

Записуйте безпечні та придатні для діагностики факти запуску:

• Версію застосунку або commit.
• Назву environment.
• Порт, на якому прослуховується застосунок.
• Назви увімкнених feature без значень secret.
• Клас host бази даних, але не пароль.
• Версію міграцій.
• Готовність health endpoint.

Шаблон timeline інциденту

Зафіксуйте:

1. Deployment ID і source commit.
2. Час початку deploy і час завершення.
3. Першу помилку, що стала причиною, у build або runtime.
4. Результат health gate.
5. Команду відновлення та deployment ID.
6. Період впливу на користувачів.
7. Відповідального за подальші дії.

Дані uptime додають доступність і час відповіді з точністю до хвилини:

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

Результат містить середній час відповіді та p95. Поєднуйте його з логами збірки та runtime-логами, щоб відрізнити інцидент під час розгортання від тривалішої деградації продуктивності.

Використовуйте довідник Dockup CLI, щоб переглянути актуальні flags для log, і security best practices для безпечного логування застосунків.

Пов’язуйте логи з історією розгортань

Рядок має цінність лише тоді, коли його можна пов’язати з правильним релізом. Зберігайте deployment ID, commit hash і час запуску поруч із log artifact. Якщо два релізи відбулися майже одночасно, самих timestamp може бути недостатньо.

dockup deployments production/api -n 20 --json

Історія deployment показує, який source був активним і який реліз досяг фінального статусу. Agent не має пов’язувати runtime exception з останнім commit, доки стан сервісу не підтвердить, що цей commit справді було розгорнуто.

Уникайте розкриття secret через логи

Помилка підключення часто спокушає розробників вивести повний URL. Натомість записуйте protocol, замаскований host, назву бази даних і категорію помилки. Для token записуйте лише безпечний fingerprint, згенерований до збереження, якщо в організації для цього є відповідна policy.

Перевіряйте artifact невдалої збірки перед передаванням за межі команди. Вивід package manager і Docker може містити URL приватних репозиторіїв, імена користувачів registry або аргументи команд, навіть якщо Dockup правильно маскує збережені environment secret.

Це робить логи збірки та runtime-логи достатньо безпечними для спільної діагностики.

Зберігайте мінімальний пакет доказів

Для кожного невдалого релізу зберігайте JSON-результат deployment, build log, відповідний фрагмент runtime, status сервісу та вибраний deployment ID для відновлення. Цей пакет достатньо малий для регулярного використання й водночас достатньо повний, щоб інший оператор міг продовжити роботу без повторного виконання непевних змін.

Підтверджуйте виправлення, а не лише нову збірку

Після успішного виправленого deployment повторіть запит або умову запуску, що спричинили помилку, і перевірте runtime-вивід на повторення проблеми. Закривайте incident лише тоді, коли початковий симптом зник, health gate пройдено, а очікувана поведінка в production підтверджена.

Замкніть цикл

Задокументуйте перевірене виправлення.

Почніть із deployment, який можна перевірити

Навмисно зробіть одну тестову збірку невдалою, збережіть її NDJSON-потік і код виходу, а потім перевірте, що ваш runbook вибирає build log, а не runtime log.

Почніть безкоштовно на app.dockup.ai. План Free коштує $0 на місяць, включає стартовий кредит $10 і підтримує один workspace, три бази даних та три deployment.

FAQ

У чому різниця між build logs і runtime logs Dockup?

Build logs охоплюють клонування, встановлення залежностей, компіляцію та створення image. Runtime logs охоплюють запущений контейнер застосунку або pods.

Як стежити за build logs Dockup у реальному часі?

Використовуйте dockup logs із --build і --follow або -f. З --json команда передає batches у форматі NDJSON і завершується, коли deployment досягає фінального статусу.

Чому build follow завершується з ненульовим кодом?

Він зберігає результат deployment. Невдала збірка має завершити з помилкою shell, CI job або завдання agent, а не створювати враження успішного потоку логів.

Що означає restarted:true у виводі runtime follow?

Це означає, що контейнер перезапустився або збережений buffer прокрутився, тому Dockup повторно передав поточний snapshot, а не непомітно втратив рядки.

Чи мають application logs містити environment secret?

Ні. Dockup маскує читання збереженої конфігурації, але не може зробити безпечними довільні secret, які застосунок виводить у log. Маскуйте credential на рівні логування застосунку.