Перейти к основному содержимому
Открыть Markdown

Наблюдаемость и диагностика

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

Диагностика​

В дашборде откройте песочницу и вкладку События. Хронология, видимая владельцу, содержит последние смены состояния, действия, восстановления и ошибки. Она доступна и для остановленных песочниц, песочниц в гибернации и песочниц со статусом failed.

Через API получите ресурс и события:

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq '{id, status, error_reason, provisioning}'

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/events" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq

Для обращения сохраните x-request-id, время, ID песочницы, HTTP-статус и публичное поле error.

Симптом: статус равен failed​

Причина. Операция жизненного цикла или обязательный шаг подготовки завершился ошибкой. Подготовка может назвать шаг и сообщение; error_reason и вкладка События дают доступный владельцу диагностический контекст.

Решение.

  1. Прочитайте новое событие ошибки и шаг подготовки, завершившийся ошибкой.
  2. Исправьте названные входные данные: например, версию шаблона, учетные данные репозитория или обязательный сервис.
  3. Используйте Перезапустить в меню действий песочницы, только если существующая песочница со статусом failed допускает восстановление. Подготовка V1 не повторяет обязательное клонирование репозитория, завершившееся ошибкой; после исправления создайте песочницу заново.
  4. Удалите неиспользуемую песочницу со статусом failed или замененную одноразовую песочницу.

Проверка. Песочница переходит в running, а при наличии подготовки — в ready.

Симптом: сервис не запускается или превью возвращает ошибку​

  1. Проверьте provisioning.steps в GET /v1/sandboxes/{id}. У упавшего шага services поле message объясняет ошибку запуска или проверки готовности.
  2. Откройте События → Логи приложения. Последние строки гостевого журнала загружаются при открытии раздела. Чтобы оставить один сервис, укажите его юнит systemd (для services[].name: "web" — web.service) и нажмите Показать; пустое поле читает журнал всех юнитов. Фонового опроса нет: новые строки — по кнопке Обновить.

Тот же журнал доступен через обычный авторизованный маршрут песочницы; администраторские права не нужны:

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/guest-logs?unit=web.service&lines=200" \
--header "Authorization: Bearer $JUSTRUN_PAT" | jq

Ответ содержит lines, truncated и необязательный note. По умолчанию читаются 200 последних строк, не больше лимита диагностики среды; unit фильтрует журнал. Полный контракт — в справочнике REST API.

Нужно право чтения песочницы: личный ресурс видят его создатель и пользователи с ролью Владелец или Администратор организации; общий ресурс организации — ее участники. Скрытые ресурсы и ресурсы другого аккаунта возвращают 404.

Чтение логов не запускает и не будит песочницу, даже при wake_on_request. Логи приложения читаются только из работающей VM: для остановленной песочницы или песочницы в гибернации маршрут возвращает пустой lines и note, а консоль показывает пояснение без запроса. Пустой ответ или ошибка журнала в note не подтверждают исправность приложения.

Неверный unit или нечисловой lines возвращает 400 request.invalid_parameter. Недоступный узел или зависимость возвращает 503.

Журнал управляющего компонента по песочнице (запуск, хранилище, сеть) доступен только операторам платформы: его строки содержат внутренние детали узла — имена датасетов ZFS, S3 URL, адреса. GET /v1/sandboxes/{id}/logs отвечает 403 permission.admin_required любой роли в аккаунте, включая владельца организации; операторы читают его в админ-консоли.

У работающей VM при необходимости проверьте systemctl status web.service --no-pager через терминал или /exec; исполнение требует права изменения. По сообщению шага или журнала исправьте настройки сервиса, затем проверьте provisioning.status: "ready" и успешную проверку здоровья сервиса.

Симптом: выполнение команды сообщает, что песочница не running​

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

Решение.

  • В дашборде выберите в меню действий песочницы Запустить для остановленной песочницы или Разбудить для песочницы в гибернации.
  • Через API вызовите /resume для stopped или /wake для hibernated, затем опрашивайте GET /v1/sandboxes/{id} до status: "running".
  • Не меняйте контракт команды при диагностике жизненного цикла. REST /exec требует строковый cmd и отдельный args.

Проверка. Выполните echo ready и получите HTTP 200, код выхода 0 и ready\n в stdout.

Симптом: HTTP 401 или 403​

Причина. 401 означает, что аутентификация bearer не принята. 403 может означать попытку изменения с валидным токеном, имеющим права Только чтение.

Решение. Проверьте адрес, значение токена, срок действия, отзыв и активный аккаунт. Используйте права Полные только для создания, выполнения, обновления и удаления.

Проверка. Сначала вызовите GET /v1/sandboxes (только чтение), затем нужную изменяющую операцию с подходящими правами.

Симптом: HTTP 429, 502 или 503​

  • 429 — квота или лимит запросов. Проверьте потребление и удалите ненужные ресурсы.
  • 502 — возможно временный сбой на участке до исходного сервера.
  • 503 — возможны нехватка ресурсов узлов или нездоровый либо исключенный из размещения узел.

Создание с неопределенным результатом повторяйте с тем же Idempotency-Key и ограниченным интервалом между повторами. Новый ключ означает новое создание.

Эскалация​

Если вкладка События и публичная ошибка не указывают решение, следуйте разделу Помощь и поддержка и передавайте только несекретные данные.