Наблюдаемость и диагностика
Начните с текущего статуса песочницы и последних событий. Не создавайте замены, пока не узнаете результат исходного запроса создания; при неопределенном ответе повторяйте исходный ключ идемпотентности.
Диагностика
В дашборде откройте песочницу и вкладку События. Хронология, видимая владельцу,
содержит последние смены состояния, действия, восстановления и ошибки. Она доступна и
для остановленных песочниц, песочниц в гибернации и песочниц со статусом 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 и вкладка События
дают доступный владельцу диагностический контекст.
Решение.
- Прочитайте новое событие ошибки и шаг подготовки, завершившийся ошибкой.
- Исправьте названные входные данные: например, версию шаблона, учетные данные репозитория или обязательный сервис.
- Используйте Перезапустить в меню действий песочницы, только если существующая
песочница со статусом
failedдопускает восстановление. Подготовка V1 не повторяет обязательное клонирование репозитория, завершившееся ошибкой; после исправления создайте песочницу заново. - Удалите неиспользуемую песочницу со статусом
failedили замененную одноразовую песочницу.
Проверка. Песочница переходит в running, а при наличии подготовки —
в ready.
Симптом: сервис не запускается или превью возвращает ошибку
- Проверьте
provisioning.stepsвGET /v1/sandboxes/{id}. У упавшего шагаservicesполеmessageобъясняет ошибку запуска или проверки готовности. - Откройте События → Логи приложения. Последние строки гостевого журнала
загружаются при открытии раздела. Чтобы оставить один сервис, укажите его
юнит 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 и ограниченным интервалом между повторами.
Новый ключ означает новое создание.
Эскалация
Если вкладка События и публичная ошибка не указывают решение, следуйте разделу Помощь и поддержка и передавайте только несекретные данные.