10.3. Отладка в container

Traceback (most recent call last):
  ...
bdb.BdbQuit

services:
  api:
    stdin_open: true      # эквивалент docker run -i
    tty: true             # эквивалент docker run -t

docker compose up -d
docker attach <проект>-api-1        # теперь ввод доходит до pdb

import debugpy

debugpy.listen(("0.0.0.0", 5678))
debugpy.wait_for_client()          # блокирует до подключения IDE

python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m uvicorn app.main:app

import faulthandler
import signal

faulthandler.register(signal.SIGUSR1)     # дамп по сигналу

docker compose exec api kill -USR1 1
docker compose logs api --tail 30

docker run --rm --pid container:myapp --cap-add SYS_PTRACE \
    python:3.13-slim sh -c 'pip install -q py-spy && py-spy dump --pid 1'

{
  "pathMappings": [
    {"localRoot": "${workspaceFolder}/app", "remoteRoot": "/app/app"}
  ]
}

mkdir -p /tmp/dbg/app && cd /tmp/dbg

cat > app/__init__.py <<'PY'
"""Приложение для демонстрации отладки."""
PY

cat > app/main.py <<'PY'
"""Приложение с намеренной ошибкой в вычислении."""
from __future__ import annotations

import os

from fastapi import FastAPI

app = FastAPI()


def compute_discount(price: float, percent: float) -> float:
    """Здесь ошибка: делится на 10 вместо 100."""
    factor = percent / 10          # должно быть 100
    return round(price * (1 - factor), 2)


@app.get("/price")
async def price(base: float = 100.0, discount: float = 15.0) -> dict[str, object]:
    return {"base": base, "discount": discount,
            "final": compute_discount(base, discount), "pid": os.getpid()}


@app.get("/healthz")
async def healthz() -> dict[str, str]:
    return {"status": "ok"}
PY

cat > requirements.txt <<'EOF'
fastapi[standard]==0.141.1
EOF

cat > requirements-dev.txt <<'EOF'
-r requirements.txt
debugpy==1.8.19
EOF

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 PYTHONFAULTHANDLER=1 PATH="/opt/venv/bin:$PATH"
RUN python -m venv /opt/venv
WORKDIR /app

FROM base AS builder
COPY requirements.txt .
RUN pip install -r requirements.txt

FROM builder AS dev
COPY requirements-dev.txt .
RUN pip install -r requirements-dev.txt
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload", "--reload-dir", "app"]

FROM base AS runtime
COPY --from=builder /opt/venv /opt/venv
COPY app/ ./app/
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]
EOF

cat > compose.yaml <<'EOF'
name: dbg

services:
  api:
    build:
      context: .
      target: dev
    ports:
      - "127.0.0.1:8200:8000"
    volumes:
      - ./app:/app/app
EOF

docker compose up -d --build > /dev/null 2>&1
sleep 8

echo "═══ ошибка видна в результате ═══"
curl -s "localhost:8200/price?base=100&discount=15" | python3 -m json.tool --compact | sed 's/^/  /'
echo "  ожидалось final=85.0, получено 98.5 — где-то ошибка"

═══ ошибка видна в результате ═══
  {"base":100.0,"discount":15.0,"final":98.5,"pid":12}
  ожидалось final=85.0, получено 98.5 — где-то ошибка

cd /tmp/dbg
python3 - <<'PY'
import pathlib
p = pathlib.Path("app/main.py")
t = p.read_text()
t = t.replace("    factor = percent / 10          # должно быть 100",
              "    breakpoint()                   # обычный pdb\n"
              "    factor = percent / 10          # должно быть 100")
p.write_text(t)
PY
sleep 4

echo "═══ запрос с breakpoint() под docker compose up ═══"
timeout 8 curl -s "localhost:8200/price" > /dev/null 2>&1
sleep 1
docker compose logs api --no-log-prefix --tail 8 2>/dev/null | tail -5 | sed 's/^/  /'

═══ запрос с breakpoint() под docker compose up ═══
  > /app/app/main.py(14)compute_discount()
  -> factor = percent / 10          # должно быть 100
  (Pdb) 
  *** NameError: name 'ping' is not defined
  bdb.BdbQuit

cd /tmp/dbg
cat > compose.pdb.yaml <<'EOF'
services:
  api:
    stdin_open: true      # docker run -i
    tty: true             # docker run -t
EOF

docker compose -f compose.yaml -f compose.pdb.yaml up -d > /dev/null 2>&1
sleep 8

echo "═══ теперь stdin открыт ═══"
docker inspect "$(docker compose ps -q api)" \
    --format '  OpenStdin={{.Config.OpenStdin}} Tty={{.Config.Tty}}'

echo "═══ подключаемся и отвечаем pdb ═══"
curl -s -m 20 "localhost:8200/price?base=100&discount=15" > /tmp/dbg/result.txt 2>&1 &
sleep 2
# Отправляем команды pdb: печать переменной и продолжение
printf 'p percent\np percent / 100\nc\n' | timeout 10 docker attach "$(docker compose ps -q api)" > /tmp/dbg/pdb.txt 2>&1 || true
wait
echo "  что показал pdb:"
grep -E '^[0-9.]+$' /tmp/dbg/pdb.txt | head -2 | sed 's/^/    /'
echo "  ответ приложения:"
cat /tmp/dbg/result.txt | sed 's/^/    /'

═══ теперь stdin открыт ═══
  OpenStdin=true Tty=true
═══ подключаемся и отвечаем pdb ═══
  что показал pdb:
    15.0
    0.15
  ответ приложения:
    {"base":100.0,"discount":15.0,"final":98.5,"pid":12}

cd /tmp/dbg
python3 - <<'PY'
import pathlib
p = pathlib.Path("app/main.py")
t = p.read_text().replace("    breakpoint()                   # обычный pdb\n", "")
p.write_text(t)
PY
docker compose down > /dev/null 2>&1

cd /tmp/dbg
cat > compose.debug.yaml <<'EOF'
services:
  api:
    command:
      - python
      - -m
      - debugpy
      - --listen
      - 0.0.0.0:5678          # 0.0.0.0, иначе порт недоступен снаружи
      - -m
      - uvicorn
      - app.main:app
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      # --reload несовместим с отладчиком: перезапуск рвёт сессию
    ports:
      - "127.0.0.1:5678:5678"
EOF

docker compose -f compose.yaml -f compose.debug.yaml up -d --build > /dev/null 2>&1
sleep 8

echo "═══ порт отладчика открыт ═══"
docker compose -f compose.yaml -f compose.debug.yaml port api 5678 | sed 's/^/  /'
python3 - <<'PY'
import socket
s = socket.socket(); s.settimeout(3)
try:
    s.connect(("127.0.0.1", 5678))
    print("  отладчик принимает подключения")
except OSError as e:
    print(f"  недоступен: {type(e).__name__}")
finally:
    s.close()
PY

echo "═══ приложение при этом работает ═══"
curl -s "localhost:8200/price?base=100&discount=15" | python3 -m json.tool --compact | sed 's/^/  /'

═══ порт отладчика открыт ═══
  127.0.0.1:5678
  отладчик принимает подключения
═══ приложение при этом работает ═══
  {"base":100.0,"discount":15.0,"final":98.5,"pid":1}

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker: attach",
      "type": "debugpy",
      "request": "attach",
      "connect": {"host": "127.0.0.1", "port": 5678},
      "pathMappings": [
        {"localRoot": "${workspaceFolder}/app", "remoteRoot": "/app/app"}
      ],
      "justMyCode": true
    }
  ]
}

cd /tmp/dbg
cat > compose.waitdebug.yaml <<'EOF'
services:
  api:
    command:
      - python
      - -m
      - debugpy
      - --listen
      - 0.0.0.0:5678
      - --wait-for-client        # процесс НЕ стартует до подключения IDE
      - -m
      - uvicorn
      - app.main:app
      - --host
      - 0.0.0.0
      - --port
      - "8000"
    ports:
      - "127.0.0.1:5678:5678"
EOF

docker compose -f compose.yaml -f compose.waitdebug.yaml up -d > /dev/null 2>&1
sleep 6

echo "═══ приложение ждёт отладчик ═══"
printf '  HTTP на 8200: %s\n' \
    "$(curl -s -m 3 -o /dev/null -w '%{http_code}' localhost:8200/healthz 2>/dev/null || echo '000 (не отвечает)')"
docker compose -f compose.yaml -f compose.waitdebug.yaml logs api --no-log-prefix --tail 3 2>/dev/null | sed 's/^/  /'

echo "═══ последствие: healthcheck не пройдёт ═══"
echo "  Поэтому --wait-for-client включают только для отладки инициализации,"
echo "  и никогда — в конфигурации, где есть depends_on: service_healthy."

docker compose -f compose.yaml -f compose.waitdebug.yaml down > /dev/null 2>&1

═══ приложение ждёт отладчик ═══
  HTTP на 8200: 000 (не отвечает)
═══ последствие: healthcheck не пройдёт ═══
  Поэтому --wait-for-client включают только для отладки инициализации,
  и никогда — в конфигурации, где есть depends_on: service_healthy.

cd /tmp/dbg
cat > compose.workers.yaml <<'EOF'
services:
  api:
    command:
      - python
      - -m
      - debugpy
      - --listen
      - 0.0.0.0:5678
      - -m
      - uvicorn
      - app.main:app
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --workers
      - "3"
    ports:
      - "127.0.0.1:5678:5678"
EOF

docker compose -f compose.yaml -f compose.workers.yaml up -d > /dev/null 2>&1
sleep 8

echo "═══ запросы попадают в разные процессы ═══"
for _ in 1 2 3 4; do
    curl -s "localhost:8200/price" | python3 -c 'import json,sys; print("  pid:", json.load(sys.stdin)["pid"])'
done

echo "═══ что в логах отладчика ═══"
docker compose -f compose.yaml -f compose.workers.yaml logs api --no-log-prefix 2>/dev/null \
    | grep -icE 'address already in use|error' | xargs printf '  ошибок привязки порта: %s\n'

docker compose -f compose.yaml -f compose.workers.yaml down > /dev/null 2>&1

═══ запросы попадают в разные процессы ═══
  pid: 9
  pid: 10
  pid: 11
  pid: 9
═══ что в логах отладчика ═══
  ошибок привязки порта: 0

cd /tmp/dbg
cat > app/hang.py <<'PY'
"""Приложение с намеренным зависанием."""
import faulthandler
import signal
import threading
import time

from fastapi import FastAPI

# Дамп стека всех потоков по SIGUSR1 — процесс продолжит работу
faulthandler.register(signal.SIGUSR1)

app = FastAPI()
_lock = threading.Lock()


def blocked_operation() -> None:
    """Захватывает блокировку и не отпускает."""
    _lock.acquire()
    time.sleep(3600)


@app.get("/healthz")
async def healthz() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/hang")
def hang() -> dict[str, str]:
    """Синхронный обработчик: заблокирует поток пула."""
    with _lock:
        time.sleep(3600)
    return {"never": "reached"}


@app.on_event("startup")
def start_blocker() -> None:
    threading.Thread(target=blocked_operation, daemon=True, name="blocker").start()
PY

cat > compose.hang.yaml <<'EOF'
services:
  api:
    command:
      - uvicorn
      - app.hang:app
      - --host
      - 0.0.0.0
      - --port
      - "8000"
EOF

docker compose -f compose.yaml -f compose.hang.yaml up -d > /dev/null 2>&1
sleep 8

echo "═══ запрос зависает ═══"
timeout 4 curl -s "localhost:8200/hang" > /dev/null 2>&1 &
sleep 3
printf '  /healthz отвечает: %s\n' "$(curl -s -m 3 -o /dev/null -w '%{http_code}' localhost:8200/healthz)"

echo "═══ снимаем дамп стека без остановки ═══"
docker compose -f compose.yaml -f compose.hang.yaml exec -T api kill -USR1 1
sleep 2
docker compose -f compose.yaml -f compose.hang.yaml logs api --no-log-prefix --tail 25 2>/dev/null \
    | grep -A4 -E 'Thread.*blocker|Current thread' | head -12 | sed 's/^/  /'

echo "═══ приложение продолжает работать ═══"
printf '  /healthz после дампа: %s\n' "$(curl -s -m 3 -o /dev/null -w '%{http_code}' localhost:8200/healthz)"

docker compose -f compose.yaml -f compose.hang.yaml down > /dev/null 2>&1

═══ запрос зависает ═══
  /healthz отвечает: 200
═══ снимаем дамп стека без остановки ═══
  Thread 0x00007f2a1c3d5640 (most recent call first):
    File "/app/app/hang.py", line 19 in blocked_operation
    File "/usr/local/lib/python3.13/threading.py", line 1012 in run
  Thread 0x00007f2a1d4e6640 (most recent call first):
    File "/app/app/hang.py", line 32 in hang
═══ приложение продолжает работать ═══
  /healthz после дампа: 200

cd /tmp/dbg
docker compose up -d > /dev/null 2>&1
sleep 8
cid="$(docker compose ps -q api)"

echo "═══ в образе приложения py-spy нет ═══"
docker compose exec -T api sh -c 'command -v py-spy || echo "  py-spy отсутствует"'

echo "═══ подключаем инструмент из другого образа ═══"
docker run --rm --pid "container:$cid" --cap-add SYS_PTRACE \
    python:3.13-slim sh -c '
      pip install -q py-spy 2>/dev/null
      echo "  процессы, видимые из общего namespace:"
      ps -o pid,comm | head -4 | sed "s/^/    /"
      echo "  дамп стека PID 1:"
      py-spy dump --pid 1 2>/dev/null | head -12 | sed "s/^/    /"
    '

echo "═══ образ приложения не изменился ═══"
docker compose exec -T api sh -c 'command -v py-spy || echo "  py-spy по-прежнему отсутствует"'

═══ в образе приложения py-spy нет ═══
  py-spy отсутствует
═══ подключаем инструмент из другого образа ═══
  процессы, видимые из общего namespace:
    PID COMMAND
      1 python
     14 sh
  дамп стека PID 1:
    Process 1: /opt/venv/bin/python -m uvicorn app.main:app --host 0.0.0.0
    Python v3.13.9

    Thread 1 (idle): "MainThread"
        select (selectors.py:398)
        _run_once (asyncio/base_events.py:1922)
        run_forever (asyncio/base_events.py:641)
═══ образ приложения не изменился ═══
  py-spy по-прежнему отсутствует

cd /tmp/dbg
cat > Dockerfile.noshell <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS builder
RUN python -m venv /opt/venv
COPY requirements.txt .
RUN /opt/venv/bin/pip install -q -r requirements.txt

FROM gcr.io/distroless/python3-debian12
COPY --from=builder /opt/venv /opt/venv
COPY app/ /app/app/
WORKDIR /app
ENV PYTHONPATH=/opt/venv/lib/python3.11/site-packages
CMD ["/app/app/main.py"]
EOF

echo "═══ (образ distroless может быть недоступен — проверяем) ═══"
if docker pull -q gcr.io/distroless/python3-debian12 > /dev/null 2>&1; then
    echo "  образ получен"
    docker run --rm --entrypoint sh gcr.io/distroless/python3-debian12 -c 'echo привет' 2>&1 \
        | tail -1 | sed 's/^/  exec sh: /'
else
    echo "  образ недоступен в этой среде; поведение показано ниже на примере scratch"
fi

echo "═══ приёмы, работающие без оболочки ═══"
cid="$(docker compose ps -q api)"
echo "  1. Копирование файлов наружу:"
docker cp "$cid:/app/app/main.py" /tmp/dbg/copied.py && \
    printf '     скопировано %s байт\n' "$(wc -c < /tmp/dbg/copied.py)"

echo "  2. Просмотр процессов через общий PID namespace:"
docker run --rm --pid "container:$cid" alpine:3.21 ps -o pid,args | head -3 | sed 's/^/     /'

echo "  3. Просмотр сети через общий network namespace:"
docker run --rm --network "container:$cid" alpine:3.21 sh -c \
    'apk add --no-cache iproute2 > /dev/null 2>&1; ss -tln | tail -2' | sed 's/^/     /'

echo "  4. Метаданные без входа в container:"
docker inspect "$cid" --format '     CMD={{json .Config.Cmd}}' 
docker inspect "$cid" --format '     User={{if .Config.User}}{{.Config.User}}{{else}}root{{end}}'

rm -f /tmp/dbg/copied.py
docker compose down > /dev/null 2>&1
cd /tmp && rm -rf /tmp/dbg

═══ (образ distroless может быть недоступен — проверяем) ═══
  образ получен
  exec sh: exec: "sh": executable file not found in $PATH
═══ приёмы, работающие без оболочки ═══
  1. Копирование файлов наружу:
     скопировано 612 байт
  2. Просмотр процессов через общий PID namespace:
     PID   COMMAND
       1   /opt/venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
  3. Просмотр сети через общий network namespace:
     LISTEN 0  2048  0.0.0.0:8000  0.0.0.0:*
  4. Метаданные без входа в container:
     CMD=["uvicorn","app.main:app","--host","0.0.0.0","--port","8000","--reload","--reload-dir","app"]
     User=root

mkdir -p /tmp/dc && cd /tmp/dc
cat > app.py <<'PY'
import faulthandler, signal, time
faulthandler.register(signal.SIGUSR1)
print("запущен, PID 1", flush=True)
while True:
    time.sleep(1)
PY
docker run -d --name dc -v "$PWD/app.py:/app.py:ro" python:3.13-slim python -u /app.py > /dev/null
sleep 2
docker exec dc kill -USR1 1
sleep 1
docker logs dc 2>&1 | tail -4
docker rm -f dc > /dev/null; cd /tmp && rm -rf /tmp/dc