Skip to content

08_Debug.md

Latest commit

 

History

History
198 lines (138 loc) · 10.5 KB

08_Debug.md

File metadata and controls

198 lines (138 loc) · 10.5 KB
Raw

Отладка и устранение неисправностей

Этот раздел нужен для быстрой локализации проблем без чтения половины проекта.

С чего начинать диагностику

Нормальный порядок диагностики такой:

  1. проверить серверный PHP log;
  2. открыть logs/ проекта;
  3. запустить php inc/cli.php help, чтобы убедиться, что bootstrap живой и CLI не падает;
  4. если проблема в маршрутизации, смотреть logs/router_error/...;
  5. если проблема в фоновых задачах, смотреть cron_agents, cron_error и health-screen.

Важно:

  • не опирайтесь на query-параметры отладки как на стабильный публичный контракт;
  • если в конкретной установке есть локальный low-level debug output в index.php, считайте это временной инженерной диагностикой, а не частью публичного API EE_FrameWork.

Production debug policy

В production должно быть так:

  • ENV_DEBUG=false;
  • display_errors=0;
  • публичного phpinfo() нет;
  • временные debug-файлы, export-пакеты и тестовые артефакты не лежат в webroot;
  • подробности ошибок уходят в logs, а пользователю отдаётся штатный response через error.php;
  • AJAX/API получают JSON-ошибку без raw exception dump.

Ad-hoc query-флаги для просмотра runtime state допустимы только как локальная временная диагностика и не должны попадать в production-инструкции.

Post-install diagnostic mode

Сразу после разворачивания проекта временная отладка допустима: в этот момент чаще всего проверяются БД, права на runtime-директории, cron, web-server rewrite и первичный bootstrap. Это отдельный post-install diagnostic mode, а не штатное production-состояние.

Правило:

  • debug должен быть явно включён и понятен администратору;
  • подробности ошибок остаются в логах, CLI или token-protected диагностике;
  • перед публикацией выполняется чеклист отключения debug;
  • ENV_DEBUG=false остаётся целевым production-состоянием.

Как работает логирование сейчас

Система логирует через Logger.

Что даёт новый слой:

  • уровни DEBUG/INFO/NOTICE/WARNING/ERROR/CRITICAL/AUDIT;
  • канал логирования;
  • request_id;
  • request context;
  • управляемую ротацию;
  • единый backend для project logs.

В админке viewer тоже умеет:

  • recent-first просмотр;
  • архивы логов;
  • summary по каналам и размерам.

Где смотреть логи

  • logs/ — project logs;
  • серверный PHP log;
  • fatal_errors.txt — shutdown/fatal;
  • admin logs viewer;
  • отдельные каналы по подсистемам вроде router_error, cache_error, property_values, cron_error.

CLI как инструмент диагностики

Для ручной диагностики и служебных запусков используйте единый entrypoint:

php inc/cli.php help

Примеры:

php inc/cli.php ops:health-check
php inc/cli.php diagnostics:file-system --json
php inc/cli.php diagnostics:search-engine --query=hotel --json

Практическое правило:

  • app/cron/ — только то, что реально ставится в scheduler;
  • ручные проверки, health-check и инженерные сценарии идут через inc/cli.php.

Для production scheduler используется один минутный wrapper:

php app/cron/run.php

А сами периодические задания хранятся в БД как cron-агенты и настраиваются в админке.

Что должно происходить при 404

Если Router не нашёл контроллер, action или документ, ошибка должна идти через:

error.php

Это касается и docs-модуля:

  • неизвестный документ не должен рендериться как «тихая внутренняя 404»;
  • он должен попадать в штатный error flow.

Чеклист: не работает маршрут

  1. Убедитесь, что файл контроллера существует.
  2. Очистите route cache.
  3. Посмотрите router_error в логах.
  4. Проверьте rewrite/front-controller конфигурацию веб-сервера.

Чеклист: не исполняются cron-агенты

  1. Убедитесь, что системный cron реально запускает php app/cron/run.php каждую минуту.
  2. Откройте /admin/health и посмотрите блок Оповещения системы: там сразу видны stalled cron, failed media queue, stale lifecycle и backup-проблемы.
  3. Проверьте /admin/cron_agents и убедитесь, что есть due-агенты, а последний запуск scheduler-а не слишком старый.
  4. Если на health-screen есть stale-состояния, сначала выполните /admin/recover_stale_operations.
  5. Уже после этого смотрите lock-статусы и лимиты max_concurrent / max_weight_per_tick.
  6. Проверьте канал cron_agents в логах и историю запусков агента.
  7. Если ошибка относится к медиа-очереди, отдельно проверьте failed и terminal_failed элементы импорта.

Что показывает /admin/health

Health-screen теперь не только считает строки в таблицах, но и поднимает alerts по operational-контурам:

  • недоступная БД;
  • отсутствующие или недоступные для записи системные пути;
  • слишком старый минутный cron;
  • актуальные ошибки cron-агентов;
  • stale lifecycle/media/backup jobs;
  • проблемная media queue;
  • низкий остаток места на диске.

Если алерт требует действия, на карточке есть прямая ссылка:

  • в /admin/cron_agents;
  • в /admin/backup;
  • или на единое восстановление /admin/recover_stale_operations.

Чеклист: сервер упирается в память

  1. Смотрите не только project logs, но и journalctl -k на oom-kill.
  2. Сначала проверяйте, не наложились ли несколько запусков php app/cron/run.php.
  3. Проверьте текущие ограничения памяти:
ENV_MEMORY_LIMIT_WEB
ENV_MEMORY_LIMIT_CLI
ENV_CRON_MEMORY_SOFT_LIMIT_MB
ENV_CRON_AGENT_MEMORY_SOFT_LIMIT_MB
ENV_MEDIA_MIRROR_MEMORY_SOFT_LIMIT_MB
  1. Если источник нагрузки — media-mirror-worker, сначала уменьшайте batch_limit, а не весь scheduler.
  2. Если задача обязана работать долго, она должна идти порциями и уважать guard-лимиты, а не держать всё в памяти одним проходом.

Чеклист: не сохраняется в БД

  1. Проверьте, что контроллер реально вызывает модель.
  2. Проверьте OperationResult.
  3. Посмотрите SQL-ошибки в логах модели.
  4. Убедитесь, что входные данные не были отфильтрованы до пустого массива.
  5. Проверьте, не откатили ли транзакцию.

Чеклист: пустой шаблон

  1. Проверьте, существует ли файл view.
  2. Убедитесь, что переменная передана через View::set().
  3. Посмотрите, не экранировали ли вы весь HTML как строку.
  4. Проверьте, не подменяет ли layout layout_content.
  5. Если публичная часть кешируется — очистите HTML cache.

Чеклист: документ /docs/... не открывается

  1. Проверьте slug в custom/docs/manifest.json.
  2. Проверьте, существует ли файл документа в custom/docs/.
  3. Убедитесь, что alias не указывает в пустоту.
  4. Проверьте, что маршрут /docs/... реально доходит до app/docs/index.php, а не режется веб-сервером раньше PHP.
  5. Очистите route cache, если недавно меняли маршрутизацию.
  6. Если документа нет, ожидайте переход в error.php, а не “тихую” внутреннюю 404.

Если вместо error-flow вы видите сырой nginx 404, проверьте ещё и конфигурацию веб-сервера: слишком широкий deny-регекс по внутренним путям может перехватывать публичный docs URL раньше, чем запрос дойдёт до PHP.

Когда лог полезнее, чем exception page

В production:

  • пользователь не должен видеть raw exception dump;
  • разработчик должен получить лог с request_id, каналом и контекстом;
  • админская viewer-страница должна помогать, а не скрывать проблему.