Отладка прикладного решения

Отладка прикладного решения#

Предупреждение

Работает только на Java 21.

Иногда программную ошибку не получается воспроизвести на тестовых стендах. В таких случаях, gs-ctk позволяет создать среду для отладки прикладного решения в условиях, максимально приближенных к тем, в которых работает основной кластер.

Для этого создается под, в котором стартует тот же сервер приложений, что и обычно, но с включенной подсистемой отладки Java. В поде также есть дополнительный сопровождающий контейнер со средой OpenVSCode Server, подключенной к данной подсистеме. Обычные пользователи не могут подключиться к данному поду без особой ссылки.

Требования#

  • gs-ctk версии >=5.1.4 (проверить командой: cat ~/nscli/version.txt)

  • Минимальные ресурсы: 12 ГБ ОЗУ, 4 ядра CPU

  • Настроенная работающая группа ресурсов с включенными книгами ресурсов global_server_share и haproxy

  • Наличие в комплекте приложений архива appsrc.zip, содержащего исходные файлы проекта

Подготовка исходного кода для отладки#

Архив appsrc.zip должен быть собран из той же версии проекта, что и applib.zip в комплекте приложений.

Флаг --build-appsrc позволяет за один запуск gsf-cli собрать каталоги applib и appsrc. Флаг
поддерживается только для SBT-проектов. В project.yaml параметр isPublishSrcFolder должен быть равен true
или отсутствовать. По умолчанию публикация исходных артефактов включена.

Локальная сборка#

Из каталога gsf-cli выполните:

./manage.sh -p <имя_проекта> build --build-appsrc --skip-publication

В Windows используйте manage.cmd с теми же параметрами.

Команда выполняет чистую SBT-сборку, затем последовательно запускает publishLibFolder и publishSrcFolder.
Флаг --skip-publication отключает загрузку в удалённый репозиторий, но не мешает созданию локальных артефактов.

Без --publish-path результат будет сохранён в каталогах:

  • workspace/sources/<имя_проекта>/application/build/publish/applib;

  • workspace/sources/<имя_проекта>/application/build/publish/appsrc.

gsf-cli проверяет, что оба набора JAR-файлов созданы. Если release уже отмечен как собранный, но локальные
applib или appsrc отсутствуют или неполны, они будут пересобраны без повторной удалённой публикации.

Сборка в CI/CD#

Для сборки в заданный каталог укажите общий корень для applib и appsrc:

./manage.sh -p "$GSF_PROJECT_NAME" build \
  --build-appsrc \
  --skip-publication \
  --publish-path "$CI_PROJECT_DIR/publish"

В этом примере будут созданы $CI_PROJECT_DIR/publish/applib и $CI_PROJECT_DIR/publish/appsrc. Их можно сохранить как
артефакты GitLab CI:

artifacts:
  paths:
    - publish/applib/
    - publish/appsrc/

Не используйте один --publish-path вместе с --all: gsf-cli отклонит такой запуск, поскольку проекты могут
перезаписать артефакты друг друга. Запускайте сборку отдельно с -p и уникальным корневым каталогом для каждого проекта.

Локальная и удалённая публикация#

--publish-path задаёт только локальный корневой каталог. Если не указывать --skip-publication, команда build также выполнит
sbt publish. При включённом isPublishSrcFolder в Maven-репозиторий будут отправлены отдельные *-sources.jar, но не весь
каталог appsrc или архив appsrc.zip.

gsf-cli создаёт каталоги с JAR-файлами, но не создаёт applib.zip и appsrc.zip. Архив appsrc.zip формируется при упаковке
комплекта приложений средствами nscli.

Если первая release-сборка выполнялась с --skip-publication, а затем артефакты нужно отправить в Maven-репозиторий,
выполните:

./manage.sh -p <имя_проекта> publish

Ручной запуск SBT-задачи#

Для старых версий gsf-cli или для диагностики можно по-прежнему запустить SBT-консоль активного проекта:

./links/active_project_sbt.sh

В Windows используйте links\active_project_sbt.cmd. В SBT-консоли выполните:

publishSrcFolder

Исходные файлы будут опубликованы в каталоге build/publish/appsrc внутри исходного проекта (в рабочем каталоге gsf-cli это workspace/sources/<имя_проекта>/application/build/publish/appsrc). Добавьте этот каталог в корень комплекта приложений под именем appsrc. При упаковке комплекта средствами nscli будет сформирован архив appsrc.zip и рассчитаны его хеш-суммы.

Инструкция по отладке#

Запуск отладчика#

Администратор включает отладку при помощи команды nscli:

~/nscli $ ./cloud_debugger.sh --namespace gs-ctk start

Укажите группу ресурсов:gs-cluster-1
Выберите книгу ресурсов, которую необходимо взять за основу облачного отладчика:global-server-share
Укажите название для отладчика:debugger-5edafd63
Точка во времени в формате эпохи Unix, до которой будет доступен отладчик (или укажите от текущего момента указав в качестве значения
"+N", где N - время в секундах):+3600
Облачный отладчик будет доступен до 03:14:08 19.01.2038
Ожидаем готовности облачного отладчика...
Ожидаем готовности облачного отладчика...
Ожидаем готовности облачного отладчика...
Облачный отладчик готов к использованию!

Для доступа к отладчику перейдите по ссылке:
(http://example.ru)/debugger/open/gs-cluster-1-debugger-1b0e4084?debugger%2Fvscode%2F%3Ftkn%3Dba0211cf-cd8a-4ba5-b2a2-a5d1791e587b%26folder%3D%2Fuser%2Fapplication

Чтобы подключиться к серверу приложений, связанному с отладчиком, перейдите по ссылке:
(http://example.ru)/debugger/open/gs-cluster-1-debugger-1b0e4084?login%2Flogin.html

Подстроку (https://example.ru) надо подменить на имя хоста, к которому обращается пользователь для подключения к HAProxy. Например:

https://globalerp.mycompany.ru/debugger/open/gs-cluster-1-debugger-1b0e4084?debugger%2Fvscode%2F%3Ftkn%3Dba0211cf-cd8a-4ba5-b2a2-a5d1791e587b%26folder%3D%2Fuser%2Fapplication

Управление отладчиками#

Для просмотра списка активных отладчиков:

./cloud_debugger.sh --namespace gs-ctk list

Для удаления отладчика:

./cloud_debugger.sh delete --namespace gs-ctk --group my-group --book debugger-mydebugger

Подключение к отладчику#

  1. Администратор передает ссылки разработчикам (или другим лицам, проводящим отладку).

  2. Разработчик переходит в отладчик и на сервер приложений по ссылкам. Важно: Используйте HTTPS для подключения. При проблемах с аутентификацией (циклическая переадресация) очистите cookies браузера. Внешний вид облачного отладчика

Настройка Visual Studio Code#

В поде облачного отладчика уже установлены OpenVSCode Server и необходимые расширения Java, Scala и Metals. Дополнительно устанавливать расширения не требуется.

  1. Подтвердите, что каталог /user/application является доверенным, и откройте вкладку Metals на боковой панели.

  2. В течение 30 секунд должна начаться индексация проекта. Дождитесь её завершения. После этого в верхней части вкладки Metals появится список используемых модулей и библиотек.

    Дождитесь завершения индексации

    Если индексация не началась, или после ее завершения модули не появились, нажмите «Import build» в секции «Build Commands» вкладки Metals.

    Библиотеки и модули успешно подгрузились

  3. На вкладке Metals выполните команду «Run doctor». В отчёте должен присутствовать build target application с отметкой в столбце «Debugging».

  4. В разделе «Packages» → «Libraries» проверьте, что доступны модули проекта и внешние зависимости.

  5. Откройте нужные модули или библиотеки и установите точки останова, щёлкнув слева от номера нужной строки.

  6. Перейдите на вкладку «Run and Debug» боковой панели, выберите конфигурацию Global Debug и нажмите «Start Debugging».

    Кнопка запуска отладки

Отладчик включен и подключен к серверу приложений, интерфейс которого доступен через вторую ссылку. Лог сервера приложений доступен по адресу /user/application/globalserver.log.

Примечание

При запуске облачного отладчика gs-ctk автоматически создаёт отдельный под, запускает Global Server с включённой удалённой отладкой и добавляет в Visual Studio Code готовую конфигурацию Global Debug. Изменять start.sh сервера приложений или создавать конфигурацию подключения вручную не требуется.

Устранение проблем#

Проблема с аутентификацией#

Если после успешной авторизации происходит переадресация на страницу входа:

  • Очистите cookies браузера для домена отладчика

  • Используйте для подключения только протокол HTTPS

Безопасность#

В ссылку для отладчика вписан токен для подключения, который используется для авторизации в OpenVSCode Server. Следовательно, без этой ссылки подключиться к отладчику невозможно.

В будущих версиях, способ авторизации может измениться.

OpenVSCode Server работает в отдельном контейнере от имени непривилегированного пользователя, не имеет прямого доступа к секретам и файловым системам других контейнеров.

Доступ к логам и подсистеме отладки предоставляет пользователю OpenVSCode Server широкие возможности по взаимодействию с системой. В будущем они будут ограничены специальным прокси-сервером протокола отладки.

Содержание