Отладка: логи, exec, healthcheck, размер образа

Отладка: логи, exec, healthcheck, размер образа

Когда контейнер не работает, алгоритм простой: логи → внутрь → проверка сети/переменных.

Логи и exec

docker compose logs -f backend
docker compose exec backend sh
env | sort

exec подключается к уже работающему контейнеру: видишь его переменные, файлы и процессы именно в том состоянии, в котором он сломался. docker compose run backend sh создаёт новый контейнер из того же образа и конфигурации сервиса - удобно для разовых задач (миграции, тесты), но состояние проблемного контейнера там не увидишь. После run добавляй --rm, иначе остановленные контейнеры копятся.

Healthcheck: HTTP / TCP / exec

Состояния healthcheck: starting -> healthy -> unhealthy; сам Docker по unhealthy не рестартит

# HTTP - для веб-сервисов с /health endpoint
healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
  interval: 10s
  timeout: 3s
  retries: 5
  start_period: 30s   # grace-период на старт (миграции, прогрев кэша)
# wget есть в alpine (busybox), а в distroless/scratch его нет - там проверку
# встраивают в сам бинарник: test: ["CMD", "/backend", "healthcheck"]

Что значат параметры и их значения по умолчанию (если параметр не указан):

  • interval - пауза между проверками, по умолчанию 30s;
  • timeout - сколько ждать ответа одной проверки, после этого она считается проваленной, по умолчанию 30s;
  • retries - сколько провалов подряд нужно, чтобы контейнер стал unhealthy, по умолчанию 3;
  • start_period - время на старт, в течение которого провалы не засчитываются, по умолчанию 0s.

Пока проверки ещё не прошли, статус starting, после успеха - healthy, после retries провалов подряд - unhealthy. Подробный вывод последних проверок (Output, ExitCode) показывает docker inspect - см. раздел ниже.

# TCP - для БД/брокеров, где нет HTTP-эндпоинта
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres -d app || exit 1"]
  interval: 5s
  timeout: 5s
  retries: 10
# exec - кастомный скрипт, если сервис экзотический
healthcheck:
  test: ["CMD", "/app/healthcheck.sh"]
Тип    Когда выбирать                       Подводный камень
────   ──────────────────────────────────   ─────────────────────────────────
HTTP   обычный REST/gRPC-сервис             /health должен быть «лёгким» -
                                            не дёргать БД на каждый probe
TCP    БД, очереди, кеши                    «порт открыт» ≠ «сервис готов»;
                                            пиши проверку через клиент сервиса
exec   нестандартные сервисы                скрипт должен работать в образе
                                            (нет `bash` в scratch/distroless!)

⚠️ healthy не значит «готов обслуживать трафик»

Docker сообщает ровно одно: команда проверки завершилась с кодом 0. Что именно она проверила - целиком на нашей совести, и здесь легко получить зелёный статус у неработающего сервиса.

Классический пример: GET /health, который отвечает 200 OK строкой {"status":"ok"}, не касаясь базы. Контейнер healthy, а каждый реальный запрос падает с ошибкой подключения к PostgreSQL.

Полезно с самого начала различать три разных вопроса:

ВопросЧто проверяемЧто делать при «нет»
liveness - процесс жив?отвечает ли приложение вообщеперезапустить контейнер
readiness - может обслуживать запрос?есть ли соединение с базой, прогрет ли кеш, применены ли миграцииубрать из балансировки, но не перезапускать
dependency health - доступны ли зависимости?база, брокер, чужой APIобычно алерт, а не рестарт

Разница между первыми двумя практическая: перезапуск сервиса, который не готов из-за недоступной базы, ничего не исправит, но добавит downtime - и при restart: always даст цикл рестартов.

Restart-политика (restart: у сервиса) говорит Docker, когда поднимать упавший контейнер: no (по умолчанию) - никогда; on-failure - только если процесс завершился с ненулевым кодом; always - всегда; unless-stopped - всегда, кроме случая, когда ты остановил контейнер руками (подробно - в уроке про деплой). На статус unhealthy ни одна политика не реагирует: срабатывает только падение процесса.

У Docker Compose один healthcheck и один статус, поэтому обычно в него кладут readiness (её и ждёт condition: service_healthy у зависимых сервисов). В Kubernetes эти проверки разделены явно - livenessProbe, readinessProbe и startupProbe, - и знание, чем они отличаются, пригодится там дословно.

⚠️ start_period важнее, чем кажется

Без start_period контейнер с долгим стартом (миграции, прогрев кэшей, загрузка моделей) станет unhealthy ещё до конца старта - и зависимые сервисы с condition: service_healthy не поднимутся. Сами Docker и compose по unhealthy не перезапускают: это делают Swarm или внешний autoheal. Kubernetes HEALTHCHECK из образа игнорирует - там работают только его собственные livenessProbe/readinessProbe. Поставь start_period чуть больше, чем худший старт.

# Зависимый сервис стартует только когда БД зелёная
services:
  backend:
    depends_on:
      db:
        condition: service_healthy

Ограничения docker logs и log rotation

docker compose logs -f --tail=100 backend  # последние 100 строк + хвост

Стандартный драйвер json-file пишет stdout/stderr контейнера в файл /var/lib/docker/containers/<id>/<id>-json.log. Без настройки этот файл растёт бесконечно - на проде типичный аварийный сценарий: за месяц диск забит логами одного болтливого сервиса.

services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"        # ротация по 10MB
        max-file: "5"          # хранить максимум 5 файлов

Альтернативы - journald (системный journal), syslog, fluentd, gelf (Graylog). На проде логи обычно отправляют в централизованный сборщик, а локальный драйвер - только аварийный буфер.

⚠️ Логи в stdout, а не в файл

12-factor app: процесс пишет логи в stdout, контейнерный runtime сам решает, куда их направить. Внутрь контейнера писать в /var/log/app.log - антипаттерн: файл пропадёт при пересоздании контейнера.

Размер образа

docker images | head
docker history <image>

ℹ️ Главная причина огромных образов

Ты копируешь в runtime весь проект с .venv, __pycache__, кешами и тестами. Multi-stage и .dockerignore спасают.

.dockerignore

.git
.venv
dist
*.md
.env
.vscode
__pycache__

Без .dockerignore Docker копирует всё - включая .git (может быть сотни МБ). Как контекст сборки связан с кэшем слоёв и почему порядок инструкций важнее любых микрооптимизаций - в уроке про Dockerfile по шагам.

Уменьшение размера образа

# Проверь размер
docker images | grep backend

# Сравни:
# golang:1.22       → ~800MB
# golang:1.22-alpine → ~250MB
# scratch            → 0MB (только бинарник)
# distroless/static → ~2MB (минимум для Go без CGO)

Рецепт для Go:

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /backend ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /backend /backend
CMD ["/backend"]

scratch vs distroless vs alpine - что выбрать

База         Размер  Что внутри                Когда выбирать
─────────    ─────   ────────────────────────  ────────────────────────────────
scratch       0      ничего (даже /tmp нет)    статический бинарь Go без CGO,
                                                shell в проде точно не понадобится
distroless/  ~2MB    CA-certs, tzdata,         Go-сервисы без CGO, которым нужны
static               без libc                   HTTPS (CA-сертификаты) и timezone
distroless/  ~20MB   + glibc                   CGO-бинарь, но без shell
base
alpine       ~5MB    musl libc + sh + apk      нужен shell для скрипта-обёртки,
              база    base                      curl/wget для дебага, CGO=1
debian-slim  ~80MB   debian минимум            CGO с зависимостями glibc;
                                                совместимость > размер

⚠️ alpine ≠ glibc

Alpine использует musl libc, а не glibc. Бинарь с CGO_ENABLED=1, собранный против glibc, в alpine просто не запустится (not found на /lib/ld-linux). Либо CGO_ENABLED=0, либо собирай в alpine-image-е.

Debugging без shell (scratch / distroless)

В distroless и scratch нет sh, поэтому привычное docker exec backend sh упадёт. Что делать:

# Вариант 1: ephemeral debug container
docker run -it --rm \
 --pid=container:my-backend \
 --net=container:my-backend \
  alpine sh
# Теперь у тебя alpine-shell в namespaces (PID, network) backend-контейнера.
# Видны его процессы, доступна его сеть.

# Вариант 2 (Kubernetes): kubectl debug
kubectl debug -it pod/backend --image=busybox --target=backend
# Вариант 3: «отладочный» tag образа со shell на тот же бинарь
FROM gcr.io/distroless/static-debian12:debug
# или
FROM busybox AS debug-runtime

distroless/static:debug включает busybox-shell - образ можно поднять для дебага, прод-образ оставить чистым.

docker stats и docker inspect для прода

docker stats --no-stream
# CONTAINER ID   NAME    CPU %   MEM USAGE / LIMIT    NET I/O      BLOCK I/O
# a1b2c3d4       backend 12.3%   120MiB / 512MiB      5MB / 2MB    1MB / 0B

Быстрый ответ на «кто жрёт ресурсы?». На проде это полезно при разовых инцидентах - для постоянного мониторинга всё равно нужны Prometheus + cadvisor.

docker inspect backend | jq '.[0].State'
# {
#   "Status": "running",
#   "Running": true,
#   "ExitCode": 0,
#   "Health": { "Status": "healthy", "FailingStreak": 0, "Log": [...] }
# }

docker inspect backend --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}'
docker inspect backend --format '{{json .Config.Env}}'   # без хитростей светит секреты

Полезные точки в inspect: State.Health (история health-проб), Mounts (что и куда смонтировано), NetworkSettings.Networks (в каких сетях контейнер), HostConfig.RestartPolicy.

Чек-лист отладки контейнера

  1. docker compose logs -f service - что пишет сервис?
  2. docker compose exec service sh - зайти внутрь, проверить env, файлы
  3. docker compose ps - статус и порты всех сервисов
  4. docker inspect container_id - полная информация (сеть, volumes, env)
  5. docker stats - CPU/RAM в реальном времени

Мини-задание

  • Добавь .dockerignore (.venv, pycache, dist, .git, .env)
  • Собери образ, проверь размер через docker images
  • Добавь healthcheck в Dockerfile или compose
  • Зайди в работающий контейнер через exec и проверь переменные (env | sort)

Итог

  • Логи - первое, на что смотришь. exec - второе. inspect - когда совсем непонятно.
  • .dockerignore и multi-stage build - два главных способа уменьшить образ.
  • Healthcheck - не декорация: compose ждёт его в depends_on, а Swarm использует для перезапуска (в Kubernetes для этого свои livenessProbe).

Типичная ошибка

Не добавлять .dockerignore и удивляться, почему образ весит 2GB. Или использовать golang:latest как runtime-образ вместо distroless или scratch.

Мини-практика (10 минут)

Возьми любой свой Dockerfile. Собери образ, запомни размер (docker images). Добавь .dockerignore. Пересобери - сравни размер. Если образ не multi-stage - сделай multi-stage (builder + runtime). Сравни ещё раз. Цель - увидеть разницу своими глазами.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.