Troubleshooting

Назначение и область применения#

Документ описывает диагностику и устранение типовых проблем в работающем контуре SmartCPD: с чего начать, куда смотреть, что сделать на месте и когда эскалировать вендору.

Это не инструкция по установке и не runbook внедрения. Первичный setup — Установка, smoke-проверки проекта — Внедрение.

Диагностика SIP-компонентов (balancer, mgw, amd), типовые SIP-ошибки и трассировка в Homer — в отдельном документе Troubleshooting SIP.

Аудитория#

инженер внедрения;
техническая эксплуатация;
support;
DevOps на стороне заказчика.

Границы документа#

Входит#

маршрут первичной диагностики;
симптом → проверки → действия;
типовые ошибки сервисов и инфраструктуры;
SIP-симптомы с точки зрения эксплуатации (кратко; детали — в Troubleshooting SIP);
граница эскалации к вендору.

Не входит#

установка и первичный setup — Установка, Docker;
ведение проекта внедрения — Внедрение;
устройство observability-контура — Мониторинг;
SIP-проектирование и call flow — SIP;
углублённая SIP-диагностика компонентов — Troubleshooting SIP;
бизнес-смысл метрик — Описание возможностей, Метрики и статистика;
обновление версий — Обновление, Release Notes.

Первичная экспресс-диагностика#

Первичная диагностика — проверка «жив ли контур» и «нет ли очевидной деградации» до углубления в логи отдельных вызовов или сервисов. Выполняйте раздел последовательно; при отклонении переходите к указанному подразделу или связанному разделу документа.

Лицензия#

Перейдите в раздел “Лицензия”. Убедитесь что лицензия загружена и не просрочена. При просроченной лицензии детекция не выполняется. Нужно обратиться к вендору за новой лицензией.

Статистика#

Перейдите в раздел “Статистика” убедитесь что за сегодня есть вызовы. Убедитесь что аудиозаписи вызовов проигрываются. Для результатов детекции human на записи слышан голос абоенента. Отсутсвие статистики может сигнализировать о проблемах с БД. Отсутсвие аудиозаписией может сигнализировать о проблемах с место на дисках

Метрики#

Перейдите в раздел “Метрики” В дашборде “Вызовы платформы” убедитесь что вызовы есть и графана из видит. В дашборде “Результаты SIP-вызовов” необходимо убедиться что:

Не фиксируются массовые ошибки в панели Timeout 408
Не фиксируются ошибки в панели Unavailable
Не фиксируются ошибки в панели SCPD Error

В дашборде “Производительность модуля детекции” необходимо убедиться что:

Значение “% Медленных проверок” не превышает 10%

В дашборде “Анализатор аудиослепков” необходимо убедиться что:

На графике “Всего шаблонов в БД” есть данные за последние 7 дней.

Модели#

Откройте веб-интерфейс и перейдите в раздел «Модели».

Убедитесь что даты загрузки Dejavu/LSTM ML-моделей не более чем 24 ч/ч.

Состояние Docker Swarm-стека#

Проверьте, что у сервисов стека нет циклических рестартов.

docker stack services <stack_name>
docker service ps --no-trunc <stack_name>_<service_name>

Если задачи постоянно пересоздаются — логи сервиса и Troubleshooting по компонентам.

Troubleshooting по симптомам#

Симптомы по качеству детекции#

Интерпретацию «нормальных» долей robot/human/silence для базы заказчика — в Описании возможностей и Метриках и статистике. Здесь — только эксплуатационная диагностика.

Резкий рост доли robot на операторах#

Симптом: на панели «Ключевые показатели» доля robot выросла более чем в 2 раза от типичной базы и держится 2+ часа.

Где смотреть: «Метрики» → «Ключевые показатели»; «Распознавание SmartCPD»; Grafana → «Производительность модуля детекции».

Возможные причины: устаревшие или повреждённые модели; деградация Dejavu/LSTM; изменение профиля детекции; нехватка CPU на worker; swap на worker-нодах.

Действия:

Проверить дату/версию моделей в портале.
Сравнить с предыдущим стабильным периодом — менялись ли SIP, профиль, кампания дайлера.
Проверить % медленных проверок и CPU worker-нод.
Просмотреть логи smartcpd на ошибки Dejavu/LSTM — smartcpd.

При отсутствии ошибок в системе чаще всего повышение доли роботов связано с массовыми обновлениями шаблонов фраз ГП. Нужно дождаться когда вендор обновит LSTM-модель, чтобы она научилась ловить новых голосовых помощников.

Эскалация: устойчивое отклонение после проверки моделей и ресурсов; массовые ERROR в Dejavu/LSTM — эскалировать вендору.

Много медленных проверок / задержки детекции#

Симптом: Grafana «Производительность модуля детекции» — доля медленных проверок > 10% по нодам.

Где смотреть: Grafana; docker stats на worker; Troubleshooting по компонентам.

Возможные причины: нехватка CPU/RAM; swap; перегрузка worker; слишком высокий CPS для sizing.

Действия:

Проверить загрузку worker-нод.
Исключить активный swap-in (vmstat 1 → поле si).
Сопоставить CPS/линии с лицензией и сайзингом.
При устойчивой перегрузке — добавить worker-ноды или снизить трафик.

Эскалация: задержки сохраняются при достаточных ресурсах и нормальном swap — вендору с метриками и логами smartcpd.

Живых абонентов сбрасывает как robot#

Симптом: операторы/заказчик фиксируют массовые сбросы на живых ответах; в статистике — robot там, где ожидался human.

Где смотреть: запись вызова в «Статистике»; логи smartcpd по Call-ID — smartcpd.

Возможные причины: слишком агрессивный preconnect (быстрый ответ < 4 с); ложное срабатывание Dejavu; некорректный профиль детекции; повреждённая модель.

Действия:

Найти проблемный вызов по времени/номеру, прослушать запись.
В логах проверить этап, на котором выставлен robot (preconnect, Dejavu, LSTM).
Сверить «Длительность набора» с дайлером.
Активировать механизм контрольной группы, понаблюдать за вызовами в которых разметка не совпадает с детекцией.

Эскалация: воспроизводимый ложный robot на эталонных вызовах после проверки профиля и моделей.

Массовые silence / no_speech.#

Симптом: высокая доля silence

Где смотреть: запись в «Статистике»; логи postconnect/VOSK в smartcpd.

Возможные причины: абонент молчит после «алло»; низкий уровень записи; проблема RTP/кодека на участке до SmartCPD.

Действия:

Прослушать запись — есть ли голос абонента после ответа.
Сравнить с эталонным smoke-сценарием silence из Внедрения §5.
При пустой/искажённой записи — проверить SIP/RTP (balancer, mgw), не только детекцию.

Эскалация: чистая запись с голосом, но стабильный silence в классификации.

Симптомы по статистике и метрикам#

Статистика пустая или записи недоступны#

Симптом: вызовы не появляются в «Статистике»; нельзя прослушать запись; CDR неполный.

Где смотреть: cdr-collector; PostgreSQL; shared storage (detections_data); логи mgw, smartcpd, balancer.

Возможные причины: недоступна БД; нет прав на storage; cdr-collector не в N/N; ошибки на этапе после детекции.

Действия:

docker stack services — состояние cdr-collector.
Логи cdr-collector и portal-api и amd на ошибки БД.
Проверить mount shared storage и права на detections_data.
Убедиться, что время на нодах синхронизировано (NTP).

Эскалация: сервисы healthy, в логах нет ошибок, БД доступна, но CDR системно не пишется.

Метрики и статистика расходятся#

Симптом: число вызовов в «Статистике» и на дашбордах Grafana заметно различается.

Где смотреть: metrics, resolver; timezone SMARTCPD_TZ и SMARTCPD_DB_TZ в setup; Мониторинг.

Возможные причины: разный интервал агрегации; некорректный DB_TZ; ручное развертывание с несовпадающими SMARTCPD_TZ и SMARTCPD_DB_TZ; проблемы сбора метрик с Docker API.

Действия:

Сверить период и timezone отчёта; убедиться, что SMARTCPD_TZ и SMARTCPD_DB_TZ совпадают.
Проверить логи metrics / resolver на ошибки docker API — Troubleshooting по компонентам.
Сопоставить с сырыми CDR в БД (при доступе DBA).

Эскалация: стабильное расхождение при совпадающих timezone и healthy metrics.

Портал, доступ и UI#

Портал не открывается#

Где смотреть: FQDN, DNS, firewall, TLS-сертификат, reverse-proxy; docker service ps для portal-frontend.

Действия: сверить параметры из Внедрения §1 → Доступ к порталу и setup; проверить curl -vk https://<fqdn>/.

Авторизация не работает#

Действия: проверить portal-api, PostgreSQL; clock skew > 1 s на нодах; блокировка пользователя.

Метрики / Grafana не открываются из портала#

Действия: health grafana, metrics, portal-frontend proxy; логи portal-api на 502/503 к backend.

Лицензия и лимиты#

Лицензия истекла или не применяется#

Симптом: предупреждения в портале; ограничение функций; рестарты smartcpd.

Действия: портал → «Лицензия»; загрузить актуальный файл; проверить срок и fingerprint/cluster — Внедрение §4.1.

Упор в лимиты CPS / линий#

Симптом: Grafana «Вызовы платформы» — упор в ceiling; отброс вызовов.

Действия: сверить фактическую нагрузку с лицензией; согласовать расширение с вендором.

Интеграции#

Markup / uploader#

Симптом: «Операторские результаты» пустые; записи в rejected; 401/403 от Markup API.

Действия:

API-ключ с cdr.canEdit.
DELAY_LAG ≥ задержки источника — Разметка.
Каталог rejected в DATA_DIR uploader.
Пробная отправка — External API → Markup API.

External API (401/403)#

Действия: срок действия API-ключа; роли и привилегии; tenant scope ключа — External API → Авторизация.

IDM#

Симптом: не синхронизируются пользователи/роли из внешней IDM.

Действия: контракт IDM API v2 — External API → IDM API v2; логи portal-api; scope tenant.

Эскалация: ошибки API с полным request/response trace.

SmartContact#

Симптом: нет рекомендаций в «Статистике» при включённой интеграции.

Действия: SmartContact URL в setup; SIP trace backend включён — Мониторинг → SIP trace; доступ SmartContact к public.cdr и схеме homer — Установка → данные до установки.

Troubleshooting по компонентам#

Краткий справочник. Используйте после локализации затронутого сервиса в Первичной экспресс-диагностике или Troubleshooting по симптомам.

Портал и управление#

portal-frontend#

Признак OK: worker processes nginx в логах; healthcheck green.
Типовые проблемы: неверный TLS/cert; reverse-proxy; недоступен portal-api.
Логи: docker service logs <stack>_portal-frontend.

portal-api#

Признак OK: gunicorn, GET /health HTTP/1.1" 200.
Типовые проблемы: недоступна PostgreSQL; ошибки миграции; timeout к license-server / billing-server.
Логи: docker service logs <stack>_portal-api.

license-server#

Признак OK: Application started on 0.0.0.0:8001.
Типовые проблемы: невалидная лицензия; ошибка чтения license file — см. Лицензия и лимиты.

billing-server#

Признак OK: Application started on 0.0.0.0:8001.
Типовые проблемы: незавершённая миграция после upgrade; недоступна БД.

Observability#

metrics#

Признак OK: started VictoriaMetrics.
Типовые проблемы:
- permission denied на /storage/flock.lock — права на metrics_data;
- cannot query dockerswarm api — доступ к Docker socket/API → Docker.

grafana#

Признак OK: HTTP Server Listen, app registry initialized.
Типовые проблемы: недоступен backend; неверный subUrl /grafana.

resolver#

Признак OK: Connected to docker daemon, Starting DNS server on 0.0.0.0:3535.
Типовые проблемы: Failed to connect to docker daemon — socket/permissions.

log2file / docker-health-exporter#

Типовые проблемы: нет архивных логов — retention, disk, путь из setup. См. Мониторинг.

Контур вызовов#

SIP-контур (balancer, mgw, amd) подробно разобран в Troubleshooting SIP: переменные сервисов, состав компонентов, типовые ошибки и трассировка в Homer.

balancer#

Признак OK: Listening on udp: …:5060; при DNS-dispatch — insert new worker, Update dispatcher.
Типовые проблемы: см. Troubleshooting SIP → типовые проблемы balancer — в т.ч. нет реакции на INVITE/OPTIONS, 401, 408, 500, отклонение из‑за SIP-trunk.

mgw#

Признак OK: Listening on udp: …:5060, udp: …:5050.
Типовые проблемы: нет связи с локальным smartcpd/amd; RTP односторонний — см. Troubleshooting SIP → ошибки mgw.

smartcpd (worker)#

Признак OK: Application startup complete.
Важно: healthcheck проверяет наличие лицензии — без license file контейнер может циклически перезапускаться.
Логи: docker service logs --since 6h <stack>_smartcpd — основной источник для разбора конкретного вызова (Call-ID / UUID в квадратных скобках).

Полный цикл в логах (штатно):

Preconnect duration — проверка времени между INVITE и 200 OK (скорость снятия трубки)
Спецсигналы в preconnect — 800 Hz, SIT и т.п.
Dejavu (preconnect) — спектрограмма vs шаблоны АО; при hashes_matched_in_input выше Confidence level → robot.
Postconnect — сигнал 425 Hz; Dejavu local/cloud; LSTM; при необходимости VOSK (ключевые слова).
Если ни одна проверка не сработала положительно → human.

Типовые ошибки:

Симптом в логах	Действие
`Ошибка в проверке Dejavu`	Повреждена БД шаблонов — запросить у вендора модели, загрузить в портале («Модели»).
`Не удалось выполнить LSTM_CLASSIFIER`	Повреждена LSTM-модель — то же: актуальный файл от вендора → портал.
Прочие `ERROR`	Собрать фрагмент логов по Call-ID и эскалировать вендору.

См. также симптомы по качеству детекции — Troubleshooting по симптомам; swap/задержки на worker — там же и сайзинг.

amd (локально на worker)#

Признак OK: Asterisk Ready.
Типовые проблемы: CALLS WILL NOT BE LOGGED — недоступна PostgreSQL для CDR asterisk; медиа-контур — см. Troubleshooting SIP → диагностика amd и CDR.

analyzer#

Признак OK: SmaptCPD_Analyzer started.
Типовые проблемы: недоступен overlay к worker/analyzer storage.

Данные#

cdr-collector#

Типовые проблемы: нет записей в статистике; ошибки записи в detections_data или БД; проверить shared storage и PostgreSQL.

redis / redis-sentinel#

Типовые проблемы: redis-sentinel 2/3 допустимо при одной service-ноде (см. Установка); иначе — quorum sentinel.

Интеграции (runtime)#

markup-uploader#

Типовые проблемы: записи в rejected; неверный DELAY_LAG; API 401/403 — Интеграции, Разметка.

cloud-connector#

Типовые проблемы: модели не обновляются; proxy/firewall до scpd.altuera.ru:5000.