Skip to content

Руководство по отладке

Отладка проектов разметки в Potato: подробное логирование, флаги отладки, разбор частых сообщений об ошибках, проблемы загрузки данных и проверки схем.

В Potato есть несколько флагов командной строки и параметров конфигурации, которые помогают отлаживать и тестировать проекты разметки. Они пригодятся при разработке и поиске неисправностей.

Конфигурация сервера

Параметры сервера можно задать прямо в YAML-файле конфигурации:

yaml
server:
  port: 8000        # Port to run on (default: 8000)
  host: "0.0.0.0"   # Host to bind to (default: 0.0.0.0)
  debug: false      # Enable Flask debug mode (default: false)

Примечание: флаги командной строки важнее значений из файла конфигурации. Например, -p 9000 переопределит server.port: 8000.

Флаги отладки

--debug

Запускает Potato в режиме отладки, чтобы проверить конфигурацию на своей машине.

bash
potato start config.yaml --debug

Что меняется:

  • Включается подробное логирование
  • Отключается тайм-аут простоя сессии
  • Админские страницы открываются без ключа для запросов с этой машины
  • Становится доступен --debug-phase, который входит за каждого посетителя как debug_user

--debug сам по себе оставляет страницу входа, а --debug-phase (см. ниже) её пропускает.

Режим отладки запускается на любом адресе, включая адрес по умолчанию 0.0.0.0, поэтому другие машины могут подключиться к серверу, а на своей вы открываете http://localhost:<port>. Две вещи остаются привязаны к этой машине. Админские страницы и админский API открываются без ключа только для запросов с неё, а не с другой машины и не через прокси; во всех остальных случаях им, как обычно, нужен API-ключ администратора. Интерактивный отладчик Werkzeug, то есть консоль Python на каждой странице ошибки, отдаётся только тогда, когда сервер привязан к 127.0.0.1. Фазы отладки действуют для всех, кто может подключиться, потому что с --debug-phase каждый посетитель входит как один и тот же debug_user, так что не включайте отладку на сервере, до которого могут добраться посторонние. Potato с 2.8.2 по 2.11.0 отказываются запускаться в режиме отладки на адресе по умолчанию 0.0.0.0, поэтому в этих версиях добавляйте --host 127.0.0.1.

--debug-log

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

bash
potato start config.yaml --debug --debug-log=all

Значения:

ЗначениеОписание
allВключает логирование и интерфейса (фронтенд), и сервера (бэкенд)
uiВключает только логирование в консоль JavaScript на фронтенде
serverВключает только логирование Python на бэкенде
noneОтключает всё отладочное логирование

Примеры:

bash
# Debug frontend issues (JavaScript errors, UI state)
potato start config.yaml --debug --debug-log=ui
 
# Debug backend issues (API calls, data processing)
potato start config.yaml --debug --debug-log=server
 
# Full debugging (both frontend and backend)
potato start config.yaml --debug --debug-log=all
 
# Quiet mode - minimal output
potato start config.yaml --debug --debug-log=none

--debug-phase

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

bash
potato start config.yaml --debug --debug-phase=annotation

Требует: флаг --debug тоже должен быть задан.

Допустимые названия фаз:

  • login: страница входа
  • consent: форма согласия
  • prestudy: опрос перед исследованием
  • instructions: страница с инструкциями
  • training: этап обучения
  • annotation: основная фаза разметки
  • poststudy: опрос после исследования
  • done: страница завершения

Примеры:

bash
# Jump directly to annotation (most common use case)
potato start config.yaml --debug --debug-phase=annotation
 
# Test post-study survey
potato start config.yaml --debug --debug-phase=poststudy
 
# Test a specific named page
potato start config.yaml --debug --debug-phase=my_custom_survey

Как это работает:

  • Каждый посетитель входит как один общий пользователь с именем debug_user
  • Все фазы до указанной пропускаются
  • Состояние пользователя выставляется так, будто он прошёл все предыдущие фазы

Сочетание флагов отладки

Флаги можно сочетать под разные сценарии отладки:

bash
# Quick annotation testing with minimal noise
potato start config.yaml --debug --debug-phase=annotation --debug-log=none
 
# Full debugging of annotation phase
potato start config.yaml --debug --debug-phase=annotation --debug-log=all
 
# Debug only backend while testing post-study
potato start config.yaml --debug --debug-phase=poststudy --debug-log=server

Другие полезные флаги

--verbose / -v

Включает подробный вывод с логированием общей работы.

bash
potato start config.yaml -v

--veryVerbose

Включает очень подробный вывод с детальной информацией о внутреннем состоянии.

bash
potato start config.yaml --veryVerbose

--port / -p

Запускает сервер на заданном порту (удобно, когда работает несколько экземпляров).

bash
potato start config.yaml -p 8080

Инструменты разработчика в браузере

Помимо флагов командной строки, для отладки пригодятся инструменты разработчика в браузере:

  1. Console: логи и ошибки JavaScript (F12 или Cmd+Option+I)
  2. Network: вызовы API между фронтендом и бэкендом
  3. Elements: DOM и стили CSS
  4. Application: хранилище сессии и cookie

Как снова включить логирование в консоль

Если логирование интерфейса было отключено через --debug-log=server или --debug-log=none, включите его снова в консоли браузера:

javascript
enableUIDebug();

Частые сценарии отладки

Тестирование новой схемы разметки

bash
# Skip to annotation with full logging
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

Отладка проблем с API

bash
# Server-only logging to focus on backend
potato start config.yaml --debug --debug-log=server

Затем изучите данные запросов и ответов на вкладке Network в браузере.

Тестирование пути пользователя

bash
# Start from the beginning with UI logging
potato start config.yaml --debug --debug-log=ui

Тестирование производительности

bash
# Minimal logging overhead
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

Решение проблем

«debug-phase requires --debug flag»

Параметр --debug-phase работает, только если задан и --debug:

bash
# Wrong
potato start config.yaml --debug-phase=annotation
 
# Correct
potato start config.yaml --debug --debug-phase=annotation

Фаза не найдена

Если указанной фазы нет в вашей конфигурации, проверьте:

  • что название фазы написано правильно
  • что фаза определена в YAML-конфигурации
  • что для собственных страниц используется точное имя страницы из конфигурации

Что почитать дальше

Подробности реализации см. в исходной документации.