13.2. Inspect, events, stats

docker inspect КОНТЕЙНЕР --format '{{.State.Status}}'
docker inspect КОНТЕЙНЕР --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'
docker inspect КОНТЕЙНЕР --format '{{json .Config.Env}}'

docker events --since 10m
docker events --filter 'event=die'
docker events --filter 'container=api' --filter 'event=health_status'
docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.Attributes.name}}'

memory.current  = anon (RSS) + page cache + kernel + ...
приложение видит = anon

docker top КОНТЕЙНЕР
docker top КОНТЕЙНЕР -eo pid,ppid,user,%cpu,%mem,cmd

docker stats --no-stream КОНТЕЙНЕР

timeout 10 docker events --format '{{json .}}'
docker events --since 5m --until 1m --format '{{json .}}'

mkdir -p /tmp/insp && cd /tmp/insp

docker run -d --name target \
    --memory 256m --cpus 0.5 \
    --health-cmd 'python -c "print(1)"' --health-interval 3s \
    -e APP_ENV=production \
    -p 18080:8000 \
    python:3.13-slim sleep 300 > /dev/null
sleep 8

echo "═══ отдельные поля ═══"
docker inspect target --format 'состояние:   {{.State.Status}}'
docker inspect target --format 'здоровье:    {{.State.Health.Status}}'
docker inspect target --format 'перезапуски: {{.RestartCount}}'
docker inspect target --format 'OOM:         {{.State.OOMKilled}}'
docker inspect target --format 'лимит памяти: {{.HostConfig.Memory}} байт'

echo "═══ несколько полей одной командой ═══"
docker inspect target --format \
'{{.Name}} | {{.State.Status}} | здоровье={{.State.Health.Status}} | память={{.HostConfig.Memory}} | перезапусков={{.RestartCount}}'

echo "═══ обход массива ═══"
docker inspect target --format '{{range .Config.Env}}  {{println .}}{{end}}' | head -5

echo "═══ вложенные структуры через json ═══"
docker inspect target --format '{{json .NetworkSettings.Ports}}' \
    | python3 -m json.tool | sed 's/^/  /'

echo "═══ условие в шаблоне ═══"
docker inspect target --format \
'{{if .State.Health}}проверка настроена: {{.State.Health.Status}}{{else}}проверки нет{{end}}'

═══ отдельные поля ═══
состояние:   running
здоровье:    healthy
перезапуски: 0
OOM:         false
лимит памяти: 268435456 байт
═══ несколько полей одной командой ═══
/target | running | здоровье=healthy | память=268435456 | перезапусков=0
═══ обход массива ═══
  APP_ENV=production
  PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  LANG=C.UTF-8
  GPG_KEY=7169605F62C751356D054A26A821E680E5FA6305
  PYTHON_VERSION=3.13.6
═══ вложенные структуры через json ═══
  {
      "8000/tcp": [
          {
              "HostIp": "0.0.0.0",
              "HostPort": "18080"
          }
      ]
  }
═══ условие в шаблоне ═══
проверка настроена: healthy

cd /tmp/insp
echo "═══ последние проверки ═══"
docker inspect target --format '{{json .State.Health}}' \
    | python3 -c "
import json, sys
h = json.load(sys.stdin)
print(f\"  статус: {h['Status']}, неудач подряд: {h['FailingStreak']}\")
print(f\"  записей в журнале: {len(h['Log'])}\")
for entry in h['Log'][-3:]:
    start = entry['Start'][11:19]
    code = entry['ExitCode']
    out = entry['Output'].strip()[:40].replace('\n', ' ')
    print(f'    {start} код={code} вывод={out!r}')
"

echo "═══ почему это важно ═══"
cat <<'TXT'
  .State.Health.Log хранит последние 5 проверок с их выводом.
  Это единственное место, где виден ВЫВОД неудачной проверки —
  в docker logs его нет, потому что проверка выполняется
  не как процесс приложения.

  При unhealthy первым делом смотрят сюда:
    docker inspect КОНТЕЙНЕР --format '{{json .State.Health}}' | python3 -m json.tool
TXT

═══ последние проверки ═══
  статус: healthy, неудач подряд: 0
  записей в журнале: 3
    10:22:14 код=0 вывод='1'
    10:22:17 код=0 вывод='1'
    10:22:20 код=0 вывод='1'
═══ почему это важно ═══
  .State.Health.Log хранит последние 5 проверок с их выводом.
  Это единственное место, где виден ВЫВОД неудачной проверки —
  в docker logs его нет, потому что проверка выполняется
  не как процесс приложения.

  При unhealthy первым делом смотрят сюда:
    docker inspect КОНТЕЙНЕР --format '{{json .State.Health}}' | python3 -m json.tool

cd /tmp/insp
echo "═══ события за последнюю минуту ═══"
docker events --since 2m --until 0s \
    --format '{{.Time}} {{.Type}}/{{.Action}} {{.Actor.Attributes.name}}' 2>/dev/null \
    | tail -8 | python3 -c "
import sys, datetime
for line in sys.stdin:
    parts = line.split(None, 2)
    if len(parts) < 3:
        continue
    ts = datetime.datetime.fromtimestamp(int(parts[0])).strftime('%H:%M:%S')
    print(f'  {ts} {parts[1]:<28} {parts[2].strip()}')
"

echo "═══ фильтр по типу события ═══"
docker events --since 5m --until 0s --filter 'event=health_status' \
    --format '{{.Action}} {{.Actor.Attributes.name}}' 2>/dev/null \
    | tail -4 | sed 's/^/  /' || echo "  событий health_status не было"

echo "═══ наблюдение в реальном времени ═══"
cat <<'TXT'
  Поток событий не заканчивается сам. В скрипте используйте
  либо --until, либо timeout:

    docker events --since 5m --until 1m --format '{{json .}}'
    timeout 10 docker events --filter 'event=die'

  Без этого команда в конвейере зависнет.
TXT

═══ события за последнюю минуту ═══
  10:22:06 container/create              target
  10:22:06 network/connect               bridge
  10:22:06 container/start               target
  10:22:11 container/health_status: healthy target
═══ фильтр по типу события ═══
  health_status: healthy target
═══ наблюдение в реальном времени ═══
  Поток событий не заканчивается сам. В скрипте используйте
  либо --until, либо timeout:

    docker events --since 5m --until 1m --format '{{json .}}'
    timeout 10 docker events --filter 'event=die'

  Без этого команда в конвейере зависнет.

cd /tmp/insp
cat > memcheck.py <<'PY'
"""Показывает разницу между RSS процесса и учётом памяти в cgroup.

cgroup учитывает page cache: файлы, прочитанные процессом
и оставшиеся в памяти ядра. Приложение своей памятью их не считает.
"""
from __future__ import annotations

import json
import os
import sys
import time
from pathlib import Path


def rss_bytes() -> int:
    """Резидентная память процесса — то, что считает своим приложение."""
    for line in Path("/proc/self/status").read_text().splitlines():
        if line.startswith("VmRSS:"):
            return int(line.split()[1]) * 1024
    return 0


def cgroup_current() -> int:
    """memory.current — то, что показывает docker stats."""
    for path in ("/sys/fs/cgroup/memory.current",
                 "/sys/fs/cgroup/memory/memory.usage_in_bytes"):
        try:
            return int(Path(path).read_text().strip())
        except OSError:
            continue
    return 0


def cgroup_stat() -> dict[str, int]:
    out = {}
    try:
        for line in Path("/sys/fs/cgroup/memory.stat").read_text().splitlines():
            k, _, v = line.partition(" ")
            if v.strip().isdigit():
                out[k] = int(v)
    except OSError:
        pass
    return out


def mib(n: int) -> str:
    return f"{n / 1024 / 1024:6.1f} МиБ"


def snapshot(label: str) -> dict[str, object]:
    st = cgroup_stat()
    return {
        "этап": label,
        "rss": rss_bytes(),
        "cgroup_current": cgroup_current(),
        "anon": st.get("anon", 0),
        "file": st.get("file", 0),
    }


if __name__ == "__main__":
    stages = [snapshot("старт")]

    # 1. Выделяем память в куче — растёт и RSS, и cgroup
    data = bytearray(80 * 1024 * 1024)
    data[::4096] = b"\x01" * (len(data) // 4096)
    stages.append(snapshot("выделено 80 МиБ в куче"))

    # 2. Создаём и читаем файл — растёт ТОЛЬКО cgroup (page cache)
    path = "/tmp/bigfile.bin"
    with open(path, "wb") as f:
        f.write(os.urandom(4 * 1024 * 1024) * 20)
    with open(path, "rb") as f:
        while f.read(1024 * 1024):
            pass
    stages.append(snapshot("прочитан файл 80 МиБ"))

    del data
    stages.append(snapshot("куча освобождена"))
    os.unlink(path)

    print(f"  {'этап':<26} {'RSS':>12} {'cgroup':>12} {'anon':>12} {'file':>12}")
    print("  " + "─" * 78)
    for s in stages:
        print(f"  {s['этап']:<26} {mib(s['rss']):>12} {mib(s['cgroup_current']):>12} "
              f"{mib(s['anon']):>12} {mib(s['file']):>12}")

    last = stages[-2]
    print()
    print(f"  Расхождение на пике: cgroup показывает "
          f"{(last['cgroup_current'] - last['rss']) / 1024 / 1024:.0f} МиБ сверх RSS.")
    print("  Это page cache — docker stats считает его использованной памятью.")
PY

echo "═══ RSS против cgroup ═══"
docker run --rm --memory 512m -v "$PWD/memcheck.py:/m.py:ro" \
    python:3.13-slim python /m.py 2>/dev/null

echo "═══ что видно снаружи ═══"
cat <<'TXT'
  docker stats берёт MEM USAGE из memory.current — колонки «cgroup».
  Приложение своей памятью считает RSS.

  Разница на пике объясняется page cache. Он не является утечкой:
  ядро освободит его при нехватке памяти. Но docker stats
  показывает его как использованную память, а MEM % считается
  именно от этого числа.

  Практическое следствие: рост MEM USAGE до предела лимита —
  сам по себе НЕ признак проблемы. Признак проблемы —
  рост anon (он же RSS), потому что anon освободить нельзя.
TXT

═══ RSS против cgroup ═══
  этап                                RSS       cgroup         anon         file
  ──────────────────────────────────────────────────────────────────────────────
  старт                          12.4 МиБ     14.1 МиБ     11.8 МиБ      1.6 МиБ
  выделено 80 МиБ в куче         92.6 МиБ     94.3 МиБ     91.9 МиБ      1.6 МиБ
  прочитан файл 80 МиБ           92.7 МиБ    174.8 МиБ     92.0 МиБ     81.9 МиБ
  куча освобождена               12.8 МиБ     95.1 МиБ     12.2 МиБ     81.9 МиБ

  Расхождение на пике: cgroup показывает 82 МиБ сверх RSS.
  Это page cache — docker stats считает его использованной памятью.
═══ что видно снаружи ═══
  docker stats берёт MEM USAGE из memory.current — колонки «cgroup».
  Приложение своей памятью считает RSS.

  Разница на пике объясняется page cache. Он не является утечкой:
  ядро освободит его при нехватке памяти. Но docker stats
  показывает его как использованную память, а MEM % считается
  именно от этого числа.

  Практическое следствие: рост MEM USAGE до предела лимита —
  сам по себе НЕ признак проблемы. Признак проблемы —
  рост anon (он же RSS), потому что anon освободить нельзя.
TXT

cd /tmp/insp
echo "═══ снимок без потока ═══"
docker stats --no-stream --format \
    'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.PIDs}}' 2>/dev/null \
    | sed 's/^/  /'

echo "═══ разбор в JSON ═══"
docker stats --no-stream --format '{{json .}}' target 2>/dev/null \
    | python3 -c "
import json, sys
d = json.load(sys.stdin)
for k in ('Name', 'CPUPerc', 'MemUsage', 'MemPerc', 'NetIO', 'BlockIO', 'PIDs'):
    print(f'  {k:<10} {d.get(k, \"-\")}')
"

echo "═══ ловушка ═══"
cat <<'TXT'
  БЕЗ --no-stream команда работает бесконечно:
    docker stats | head -3        # зависнет
    docker stats --no-stream      # даст снимок и завершится

  Для расчёта CPU % нужны ДВА замера, поэтому даже --no-stream
  занимает около секунды. В цикле по многим container'ам это
  складывается — берите все сразу одним вызовом.
TXT

═══ снимок без потока ═══
  NAME      CPU %     MEM USAGE / LIMIT     MEM %     PIDS
  target    0.00%     1.043MiB / 256MiB     0.41%     1
═══ разбор в JSON ═══
  Name       target
  CPUPerc    0.00%
  MemUsage   1.043MiB / 256MiB
  MemPerc    0.41%
  NetIO      1.02kB / 0B
  BlockIO    0B / 0B
  PIDs       1
═══ ловушка ═══
  БЕЗ --no-stream команда работает бесконечно:
    docker stats | head -3        # зависнет
    docker stats --no-stream      # даст снимок и завершится

  Для расчёта CPU % нужны ДВА замера, поэтому даже --no-stream
  занимает около секунды. В цикле по многим container'ам это
  складывается — берите все сразу одним вызовом.

cd /tmp/insp
echo "═══ процессы container с точки зрения host ═══"
docker top target 2>/dev/null | sed 's/^/  /'

echo "═══ тот же процесс изнутри ═══"
docker exec target sh -c 'ps -o pid,ppid,cmd 2>/dev/null || cat /proc/1/comm' 2>/dev/null \
    | sed 's/^/  /' || echo "  ps в образе нет"

echo "═══ соответствие PID ═══"
host_pid="$(docker inspect target --format '{{.State.Pid}}')"
echo "  PID на host:      $host_pid"
if sudo test -r "/proc/$host_pid/status" 2>/dev/null; then
    sudo grep -E '^NSpid|^Name' "/proc/$host_pid/status" | sed 's/^/  /'
else
    cat <<'TXT'
  PID внутри:       1
  (проверка через /proc/PID/status требует прав; поле NSpid
   перечисляет PID процесса во всех вложенных namespace:
   первое число — PID на host, последнее — внутри container)
TXT
fi

echo "═══ зачем это нужно ═══"
cat <<'TXT'
  Инструменты host — strace, gdb, py-spy, чтение /proc —
  работают с PID НА HOST. Внутри container тот же процесс
  имеет PID 1.

  Получить PID на host:
    docker inspect КОНТЕЙНЕР --format '{{.State.Pid}}'

  Дальше:
    sudo strace -p $PID
    sudo cat /proc/$PID/status
    sudo ls -l /proc/$PID/fd | wc -l     # число открытых дескрипторов
TXT

═══ процессы container с точки зрения host ═══
  UID    PID    PPID   C   STIME   TTY   TIME       CMD
  root   48213  48190  0   10:22   ?     00:00:00   sleep 300
═══ тот же процесс изнутри ═══
  PID  PPID CMD
    1     0 sleep 300
   28     0 sh -o pid,ppid,cmd
═══ соответствие PID ═══
  PID на host:      48213
  PID внутри:       1
  (проверка через /proc/PID/status требует прав; поле NSpid
   перечисляет PID процесса во всех вложенных namespace:
   первое число — PID на host, последнее — внутри container)
═══ зачем это нужно ═══
  Инструменты host — strace, gdb, py-spy, чтение /proc —
  работают с PID НА HOST. Внутри container тот же процесс
  имеет PID 1.

  Получить PID на host:
    docker inspect КОНТЕЙНЕР --format '{{.State.Pid}}'

  Дальше:
    sudo strace -p $PID
    sudo cat /proc/$PID/status
    sudo ls -l /proc/$PID/fd | wc -l     # число открытых дескрипторов

cd /tmp/insp
cat > snapshot.sh <<'SH'
#!/usr/bin/env bash
# Снимок состояния всех container'ов: факты, а не догадки.
set -uo pipefail

printf '\n  %-16s %-9s %-10s %-8s %-18s %-7s %s\n' \
    "ИМЯ" "СТАТУС" "ЗДОРОВЬЕ" "ПЕРЕЗАП" "ПАМЯТЬ" "CPU" "PID host"
printf '  %s\n' "──────────────────────────────────────────────────────────────────────────────────"

# Один вызов stats на всех — экономит секунду на каждом container
stats_json="$(docker stats --no-stream --format '{{json .}}' 2>/dev/null \
    | python3 -c "
import json, sys
out = {}
for line in sys.stdin:
    line = line.strip()
    if not line:
        continue
    d = json.loads(line)
    out[d['Name']] = {'mem': d.get('MemUsage', '-'), 'cpu': d.get('CPUPerc', '-')}
print(json.dumps(out))
" 2>/dev/null || echo '{}')"

while read -r name; do
    [ -z "$name" ] && continue
    read -r status health restarts pid oom exitcode <<EOF
$(docker inspect "$name" --format \
'{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}—{{end}} {{.RestartCount}} {{.State.Pid}} {{.State.OOMKilled}} {{.State.ExitCode}}' 2>/dev/null)
EOF
    mem="$(echo "$stats_json" | python3 -c "
import json, sys
print(json.load(sys.stdin).get('$name', {}).get('mem', '-'))
" 2>/dev/null)"
    cpu="$(echo "$stats_json" | python3 -c "
import json, sys
print(json.load(sys.stdin).get('$name', {}).get('cpu', '-'))
" 2>/dev/null)"

    printf '  %-16s %-9s %-10s %-8s %-18s %-7s %s\n' \
        "${name:0:16}" "$status" "$health" "$restarts" "${mem:--}" "${cpu:--}" "$pid"

    # Признаки, требующие внимания
    [ "$oom" = "true" ] && printf '      ⚠ убит по нехватке памяти (OOM)\n'
    [ "$restarts" -gt 3 ] 2>/dev/null && printf '      ⚠ перезапусков: %s — вероятен restart loop\n' "$restarts"
    [ "$health" = "unhealthy" ] && printf '      ⚠ проверка здоровья не проходит — см. .State.Health.Log\n'
    [ "$status" = "exited" ] && [ "$exitcode" != "0" ] && \
        printf '      ⚠ завершился с кодом %s\n' "$exitcode"
done < <(docker ps -a --format '{{.Names}}' 2>/dev/null | head -20)

printf '\n'
SH
chmod +x snapshot.sh

echo "═══ снимок состояния ═══"
docker run -d --name failed alpine:3.21 sh -c 'exit 7' > /dev/null 2>&1
sleep 2
./snapshot.sh
docker rm -f target failed > /dev/null 2>&1
cd /tmp && rm -rf /tmp/insp

═══ снимок состояния ═══

  ИМЯ              СТАТУС    ЗДОРОВЬЕ   ПЕРЕЗАП  ПАМЯТЬ             CPU     PID host
  ──────────────────────────────────────────────────────────────────────────────────
  failed           exited    —          0        -                  -       0
      ⚠ завершился с кодом 7
  target           running   healthy    0        1.043MiB / 256MiB  0.00%   48213

docker inspect КОНТЕЙНЕР --format '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}} {{.RestartCount}}'
docker inspect КОНТЕЙНЕР --format '{{json .State.Health}}' | python3 -m json.tool
docker events --since 5m --until 0s --filter "container=КОНТЕЙНЕР" --format '{{.Action}}'
docker stats --no-stream --format '{{json .}}' КОНТЕЙНЕР