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

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

## Диагностика[​](#diagnose "Прямая ссылка на Диагностика")

В дашборде откройте песочницу и вкладку *События*. Хронология, видимая владельцу, содержит последние смены состояния, действия, восстановления и ошибки. Она доступна и для остановленных песочниц, песочниц в гибернации и песочниц со статусом `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`[​](#symptom-status-is-failed "Прямая ссылка на symptom-status-is-failed")

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

**Решение.**

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

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

## Симптом: сервис не запускается или превью возвращает ошибку[​](#symptom-a-service-will-not-start-or-its-preview-returns-an-error "Прямая ссылка на Симптом: сервис не запускается или превью возвращает ошибку")

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](/api-reference/rest.md).

Нужно право чтения песочницы: личный ресурс видят его создатель и пользователи с ролью *Владелец* или *Администратор* организации; общий ресурс организации — ее участники. Скрытые ресурсы и ресурсы другого аккаунта возвращают `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`[​](#symptom-exec-says-the-sandbox-is-not-running "Прямая ссылка на symptom-exec-says-the-sandbox-is-not-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`[​](#symptom-http-401-or-403 "Прямая ссылка на symptom-http-401-or-403")

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

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

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

## Симптом: HTTP `429`, `502` или `503`[​](#symptom-http-429-502-or-503 "Прямая ссылка на symptom-http-429-502-or-503")

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

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

## Эскалация[​](#escalate "Прямая ссылка на Эскалация")

Если вкладка *События* и публичная ошибка не указывают решение, следуйте разделу [Помощь и поддержка](/support.md) и передавайте только несекретные данные.

## См. также[​](#related "Прямая ссылка на См. также")

* [Создание песочницы](/sandboxes/create-a-sandbox.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Ошибки и ограничения частоты запросов](/developers/errors-and-rate-limits)
