Устранение проблем и FAQ
Проверяйте доступ, готовность, сбор и сохранённые данные по очереди.
Агент не подключается
Заголовок раздела «Агент не подключается»Начните с базовых вещей: заданный gRPC endpoint, разрешение имени, сетевая доступность из кластера и доверие к TLS. Затем токен: файл лежит по указанному пути, содержит сохранённое одноразовое значение и не отозван. Само значение никогда не вставляйте в обращение в поддержку. После ротации или любого изменения конфигурации выполните rollout DaemonSet: эта версия не перечитывает токены на лету.
Если агент сообщает “no native certs found”, в контейнере нет доступного системного хранилища доверенных CA. Используйте образ агента с пакетом ca-certificates и непустым файлом /etc/ssl/certs/ca-certificates.crt, затем выполните rollout DaemonSet. Оставьте проверку TLS включённой; для Okoscope Cloud не нужен Secret с частным CA.
Работающий Pod не доказывает ни того, что зонды подключились, ни того, что поток прошёл аутентификацию. Прочитайте журналы агента и счётчики возможностей и потерь. Если подключить зонды не удалось, проверьте BTF, cgroup v2, версию и архитектуру ядра, тома узла и явно выданные capabilities. Отсутствующий обязательный хук нужно чинить, а не прятать, отключая проверки готовности.
Нет событий или подробностей
Заголовок раздела «Нет событий или подробностей»Сначала убедитесь, что смотрите в нужное место: организация, проект, приложение и временной интервал. Затем сверьте namespace, имя Deployment и метки с настроенным селектором. Создайте новую активность уже после подключения потока: просто работающий процесс нового события запуска не даёт. И только потом проверьте, включён ли нужный класс событий, и посмотрите счётчики фильтрации, скорости, очередей и потерь на уровне ядра.
Если счётчики есть, а примеров нет, дело обычно в покрытии и сроках хранения: числовая история не восстанавливает содержимое событий. Пропуски в файловых наблюдениях чаще всего объясняются относительными путями, неподдерживаемыми вызовами, утраченным соответствием дескриптора или исключённым префиксом; пропуски в DNS — шифрованием, попаданием в кэш, истёкшим TTL или трафиком, который ни с чем не совпал. И в том, и в другом случае отсутствие данных не равно отсутствию активности.
Веб-интерфейс не запускается
Заголовок раздела «Веб-интерфейс не запускается»Защищённая страница сначала проверяет совместимость сервера и только затем сессию, поэтому по виду ошибки можно понять, какая проверка не прошла. Посмотрите на /readyz и /api/v1/build-info, на то, как обратный прокси маршрутизирует API, на состояние миграций и на настроенный браузерный origin. Если сессия просто истекла, войдите заново — и учтите, что повтор операции не превратит участника организации во владельца или системного администратора.
Если logout или изменяющий состояние POST либо PUT завершается ошибкой untrusted_origin, хотя страницы и GET-запросы работают, посимвольно сравните Origin браузера с доверенным значением. Ingress, созданный чартом, автоматически доверяет выведенному Origin — https с ingress.web.tlsSecret, иначе http; внешний ingress и альтернативные адреса браузера нужно перечислить в server.corsOrigins. Проверьте scheme, host и нестандартный порт и удалите wildcard, путь, query-параметры, fragment и завершающий слеш.
Документация доступна без входа и без работающего API — уже поэтому она сама по себе полезный сигнал. Если обновление прямой ссылки вида Okoscope Cloud — Быстрый старт приводит к ошибке веб-сервера, значит для неё не настроен тот же SPA fallback, что и для остальных маршрутов интерфейса. А если регистрация недоступна, запросите доступ у оператора установки, а не считайте, что у вас неверный пароль.
Уведомление не пришло
Заголовок раздела «Уведомление не пришло»Идите по порядку: есть ли для находки запись доставки, включены ли получатель и правило и что говорит состояние обработчика — отключён, повторяет или сбоит. Затем прочитайте ограниченный список попыток: ошибки получателя, тайм-ауты, проблемы DNS или TLS, неудачную проверку подписи. Проблемы с доставкой не делают основной API приёма событий неготовым, так что не путайте одно с другим.
Восстановлением пользуйтесь, только когда понимаете, что оно сделает. Повтор сохраняет идентификатор доставки и может отправить получателю ещё один запрос, то есть рассчитывает на то, что получатель отсеивает дубликаты; отмена может столкнуться с уже идущей работой. Обращаясь в поддержку, приложите версии, время, несекретную конфигурацию и ограниченную выдержку из ошибок и счётчиков — без токенов, закрытых URL и чувствительных данных нагрузок.