Логи сборки и выполнения: отладка деплоев Dockup

Логи сборки и выполнения отвечают на разные вопросы. Логи сборки объясняют, как из исходного кода был создан образ и почему этот процесс завершился ошибкой. Логи выполнения показывают, что происходило с собранным приложением после запуска контейнера или рабочей нагрузки Kubernetes.

Чтение неправильного потока отнимает время. Отсутствующая зависимость во время создания образа никогда не появится в логах выполнения, а успешно собранный образ, который аварийно завершается при запуске, может иметь совершенно чистый вывод сборки.

В чём разница между логами сборки и выполнения?

Выбирайте поток в зависимости от этапа деплоя:

Этап	Типичный статус	Нужный лог	Частые сбои
Клонирование	cloning	Сборка	Доступ к репозиторию, ветка
Установка зависимостей	building	Сборка	Lockfile, registry, пакет
Компиляция/сборка бандла	building	Сборка	Ошибки типов, память, отсутствующие файлы
Запуск образа	deploying	Выполнение и health	Команда запуска, порт, права
Работающий сервис	running	Выполнение	Исключения, сбои зависимостей
Проверка готовности	deploying	Выполнение и конфигурация health	Неправильный путь, медленный запуск

Прочитайте последние логи сборки:

dockup logs production/api --build --json

Прочитайте логи выполнения работающего сервиса:

dockup logs production/api --json

Запросите больше строк выполнения, если нужное событие произошло давно:

dockup logs production/api -n 500 --json

Ответ JSON содержит целевой объект и тип лога, что помогает агенту не смешивать несвязанные потоки.

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

Режим follow передаёт новые строки, опрашивая текущий снимок:

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

В режиме JSON вывод имеет формат NDJSON: один объект на строку и на пакет. Потребитель может обрабатывать каждую строку по мере поступления.

Последний пакет обозначает итоговый результат сборки. Команда автоматически завершается при успешном или неуспешном завершении деплоя и возвращает ненулевой код выхода при ошибке. Поэтому её удобно использовать в агенте или CI-задаче без написанного вручную цикла проверки статуса.

Отслеживание выполнения работает аналогично:

dockup logs production/api -f --json

Каждый пакет содержит поле restarted. Если restarted:true, контейнер перезапустился или сохранённый буфер логов был сброшен, поэтому Dockup повторно передаёт весь текущий снимок, а не молча пропускает строки.

Интервал опроса по умолчанию составляет 2 секунды. Используйте документированный --interval, только если есть конкретная необходимость изменить частоту опроса.

Как диагностировать неудачную сборку?

Начните с итогового результата деплоя:

dockup deploy production/api --wait --json

Если команда завершается со статусом deploy_failed, получите лог сборки и найдите первую первопричинную ошибку, а не последнее каскадное сообщение.

Полезная последовательность действий:

1. Подтвердите целевой объект и ID деплоя.
2. Определите этап: клонирование, установка, компиляция или создание образа.
3. Найдите первую ошибку, не связанную с повторными попытками.
4. Сопоставьте способ сборки с назначением репозитория.
5. По возможности воспроизведите проблему из чистого клона.
6. Внесите одно точечное изменение.
7. Повторите деплой с --wait.

К распространённым сбоям Nixpacks относятся нераспознанный корень проекта, отсутствующий lockfile, отсутствие стандартного скрипта запуска или необходимость нативного пакета. К распространённым сбоям Dockerfile относятся неправильный контекст сборки, отсутствующий скопированный артефакт, недоступный базовый образ или ошибка в инструкции RUN.

Руководство Nixpacks vs Dockerfile содержит схему выбора системы сборки.

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

Как диагностировать сбой выполнения или ошибку health-проверки?

Успешно собранный образ всё равно может не пройти этап переключения трафика. Проверьте состояние сервиса и логи выполнения:

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

Проверьте следующее:

• Процесс завершается сразу после запуска.
• Приложение использует неправильный порт.
• Приложение слушает 127.0.0.1, а не все интерфейсы.
• Отсутствует обязательный ключ окружения.
• Не удаётся подключиться к базе данных или Redis.
• Права доступа к файлам блокируют запуск.
• Health-путь возвращает статус, не соответствующий успешному ответу.
• Запуск занимает больше времени, чем допускает настроенное число повторных проверок.
• Миграция завершается ошибкой или запускается параллельно с другой миграцией.

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

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

Не ослабляйте проверку готовности только для того, чтобы пропустить сломанный релиз. Если приложению действительно требуется больше времени на запуск, измените политику на основании фактов и сохраните endpoint, который по-прежнему подтверждает готовность.

Изменения окружения требуют нового деплоя. Если отсутствующий секрет был добавлен, выполните деплой ещё раз и дождитесь его завершения: перезапуск старого контейнера не применяет новое целевое окружение.

Как агентам разбирать NDJSON, не теряя код выхода?

Агент или скрипт должен читать каждую строку JSON, сохраняя статус процесса. Не передавайте вывод в команду, которая скрывает исходный код выхода, если не используете pipefail.

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

С pipefail команда Dockup сохраняет ненулевой код выхода при ошибке, даже если tee завершилась успешно.

Потребитель может независимо обрабатывать каждый объект:

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

Сохраняйте исходный артефакт NDJSON. Читаемый фрагмент удобен для pull request или инцидента, но исходные поля сохраняют маркеры перезапуска, статус и сигналы завершения.

Общие принципы машинного интерфейса описаны в статье 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

Затем классифицируйте инцидент:

Классификация	Признак	Следующее действие
Исходный код/сборка	Ошибка в логе сборки	Исправить репозиторий или описание сборки
Конфигурация	Отсутствует или неправильно задано окружение либо порт	Исправить конфигурацию и выполнить новый деплой
Готовность	Приложение работает, health-проверка не проходит	Исправить endpoint или обоснованно изменить тайминги
Зависимость выполнения	Исключение при подключении	Проверить базу данных, сеть и учётные данные
Регрессия	Предыдущая версия работала	Рассмотреть откат по известному ID
Неопределённость платформы	Тайм-аут, нет итогового состояния	Проверить статус перед повторной попыткой

Откатывайте только после определения известного предыдущего деплоя:

dockup rollback <deploymentId> production/api --json

Сначала сохраните ID неудачного деплоя и логи. Откат восстанавливает доступность сервиса, но не объясняет первопричину.

Статья о деплоях без простоя объясняет, почему неудачная проверка готовности может защищать рабочий трафик.

Как сделать production-логи полезными?

Dockup умеет получать вывод, но качество логов зависит от приложения. Предпочтительны структурированные записи: одно событие на запись, временная метка, уровень важности, ID запроса или трассировки, имя компонента и безопасное описание ошибки.

Никогда не записывайте в логи токены доступа, URL баз данных, пароли, полные заголовки авторизации или персональные данные, не необходимые для работы системы. Маскирование секретов в конфигурации Dockup не редактирует произвольный вывод приложения.

Записывайте безопасные и полезные для диагностики сведения о запуске:

• Версия приложения или commit.
• Имя окружения.
• Порт, на котором приложение принимает соединения.
• Имена включённых функций без значений секретов.
• Класс хоста базы данных, но не пароль.
• Версия миграций.
• Готовность health endpoint.

Шаблон временной шкалы инцидента

Зафиксируйте:

1. ID деплоя и исходный commit.
2. Время начала деплоя и время его завершения.
3. Первую первопричинную ошибку сборки или выполнения.
4. Результат проверки готовности.
5. Команду восстановления и ID деплоя.
6. Период влияния на пользователей.
7. Ответственного за последующие действия.

Данные об uptime дополняют картину доступности и времени ответа с точностью до минуты:

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

Результат содержит среднее время ответа и p95. Сочетайте эти данные с логами сборки и выполнения, чтобы отличить инцидент деплоя от более продолжительной деградации производительности.

Используйте справочник Dockup CLI для актуальных флагов работы с логами и раздел о лучших практиках безопасности для безопасного логирования приложения.

Сопоставляйте логи с историей деплоев

Строка лога полезна только тогда, когда её можно связать с правильным релизом. Храните рядом с артефактом логов ID деплоя, hash commit и время запуска. Если два релиза произошли почти одновременно, одних временных меток может быть недостаточно.

dockup deployments production/api -n 20 --json

История деплоев показывает, какой исходный код был активен и какой релиз достиг итогового состояния. Агент не должен связывать исключение выполнения с последним commit, пока состояние сервиса не подтвердит, что этот commit действительно был развёрнут.

Не допускайте утечки секретов через логи

Ошибка подключения часто подталкивает разработчиков вывести полный URL. Вместо этого записывайте протокол, замаскированный хост, имя базы данных и категорию ошибки. Для токенов записывайте только безопасный fingerprint, созданный до сохранения, если в организации это предусмотрено политикой.

Проверяйте артефакты неудачной сборки перед передачей за пределы команды. Вывод менеджера пакетов и Docker может содержать URL приватных репозиториев, имена пользователей registry или аргументы команд, даже если Dockup корректно маскирует сохранённые секреты окружения.

Так логи сборки и выполнения становятся достаточно безопасными для совместной диагностики.

Сохраняйте минимальный набор доказательств

Для каждого неудачного релиза сохраняйте JSON с результатом деплоя, лог сборки, соответствующий фрагмент логов выполнения, статус сервиса и выбранный ID деплоя для восстановления. Этот набор достаточно компактен для регулярного использования и достаточно полон, чтобы другой оператор мог продолжить работу без повторного выполнения потенциально рискованных изменений.

Проверяйте исправление, а не только новую сборку

После успешного деплоя с исправлением повторите проблемный запрос или условие запуска и проследите за логами выполнения, чтобы убедиться, что проблема не повторяется. Закрывайте инцидент только после того, как исходный симптом исчез, проверка готовности пройдена, а ожидаемое поведение в production подтверждено.

Замыкайте цикл

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

Начните с проверяемого деплоя

Принудительно завершите одну тестовую сборку ошибкой, сохраните её поток NDJSON и код выхода, затем убедитесь, что ваш runbook выбирает лог сборки, а не лог выполнения.

Начните бесплатно на app.dockup.ai. Тариф Free стоит $0 в месяц, включает стартовый кредит $10 и поддерживает один workspace, три базы данных и три деплоя.

FAQ

В чём разница между логами сборки и выполнения Dockup?

Логи сборки охватывают клонирование, установку зависимостей, компиляцию и создание образа. Логи выполнения охватывают запущенный контейнер приложения или pods.

Как просматривать логи сборки Dockup в реальном времени?

Используйте dockup logs с параметрами --build и --follow или -f. С параметром --json команда выдаёт пакеты NDJSON и завершает работу при достижении деплоем итогового состояния.

Почему follow для сборки завершается с ненулевым кодом?

Он сохраняет результат деплоя. Неудачная сборка должна завершить с ошибкой вызывающую shell-команду, CI-задачу или задачу агента, а не выглядеть как успешно завершившийся поток логов.

Что означает restarted:true в выводе follow для выполнения?

Это означает, что контейнер перезапустился или сохранённый буфер был сброшен, поэтому Dockup снова вывел текущий снимок, не теряя строки незаметно.

Должны ли логи приложения содержать секреты окружения?

Нет. Dockup маскирует чтение сохранённой конфигурации, но не может сделать безопасными произвольные секреты, выведенные приложением. Удаляйте учётные данные на уровне логирования приложения.