Мониторинг и диагностика

Что контролировать администратору

Объект

Проверка

integrations/camel-dsl@mango-call-recordings-sync

Состояние STARTED; в логах нет ошибки запуска контекста.

Сервисы

Доступны ecos-integrations, RabbitMQ, Records API, MANGO OFFICE API и сервис распознавания. Конечная точка stt-sidecar доступна именно из среды запуска интеграции.

mango-events и mango-recordings

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

mango-recordings-retry-*

Наличие сообщений означает ожидание повторов. Обычных потребителей в этих очередях нет по замыслу. Длительное накопление требует проверки целевого exchange, привязок очередей и состояния RabbitMQ.

mango-events-dlq и mango-recordings-dlq

Любое сообщение требует разбора; автоматически эти очереди не опустошаются, оповещений об их заполнении нет.

Карточка активности

Статус обработки аудиозаписи, аудиофайл, длительность, расшифровка. Отсутствие только AI-резюме проверяется отдельно от сохранения аудио.

Логи интеграции

Ошибки по entry_id звонка; строки scheduled for retry с номером попытки и задержкой; ошибки публикации, сохранения статуса и is LOST.

Для наблюдения за очередями используйте RabbitMQ Management выбранного стенда. Сопоставляйте entry_id из логов и сообщения с полем активности recording-aspect:meetingUrl вида mango://entry/<entry_id>.

Лог микросервиса

Интеграция выводит сообщения в лог микросервиса ecos-integrations:

  • все сообщения начинаются с префикса Mango:, и фильтровать лог надёжнее всего по нему;

  • сообщения шагов маршрута выводятся в логгеры с именами подмаршрутов (mango-webhook-request, mango-download-recording, mango-transcribe-recording и т. д.);

  • сообщения об отложенных повторах и о параметре retryHttpStatuses выводятся в логгеры классов ru.citeck.ecos.integrations.domain.telephony.RecordingRetryProcessor и ru.citeck.ecos.integrations.domain.telephony.RecordingFailurePolicyProcessor;

  • код ВАТС и подпись в логе маскируются.

Журнал синхронизации (действие «Посмотреть лог синхронизации» в журнале Camel DSL) этим маршрутом не ведётся.

Сообщения лога

Сообщение (фрагмент)

Уровень

Значение

activity … of call … is created

INFO

Создана активность звонка

is attached to … (N active candidates in …)

INFO

Звонок привязан к найденной сделке или лиду

created the lead

INFO

По звонку создан лид

is already attached to …, no second lead is created

INFO

Повторная обработка итога вызова, звонок уже привязан

event of call … skipped - <причина>

INFO

Уведомление пропущено (исходящий или пропущенный звонок, уведомление о статусе записи и т. п.)

gives no phone key

INFO

Из номера не получен нормализованный номер (скрытый или короткий номер)

resolved to no target

INFO

Сделка или лид не найдены и не созданы, активность не создана

is queued for

INFO

Звонок поставлен в очередь на загрузку аудиозаписи

is downloaded, N bytes

INFO

Аудиозапись загружена

is transcribed

INFO

Аудиозапись распознана

has no transcription to summarize

INFO

Расшифровка пуста, резюме не запрашивалось

event is dropped

INFO

Уведомление о записи пришло для звонка без активности и отброшено; для исходящих, внутренних и пропущенных звонков с аудиозаписью это штатная ситуация

the record/added of recording … is dropped

INFO

Аудиозапись звонка уже сохранена; повторное уведомление или аудиозапись второго участка переведённого звонка отброшены

scheduled for retry N in M ms

INFO

Запланирован отложенный повтор обработки аудиозаписи

not available at Mango yet (HTTP 404), the download is given back to the caller to be retried

WARN

Файл ещё недоступен через API Mango. Скачивание будет повторено по расписанию; это не немедленный окончательный отказ

matched several records

WARN

Номер совпал с несколькими сделками, лидами или контрагентами, приведены ссылки на кандидатов

an older active record may have been missed

WARN

По номеру найдено 100 и более сделок или лидов, более старая активная сделка или лид могли не попасть в выборку

activities with the same key

WARN

У звонка несколько активностей, используется самая ранняя

saved without a summary

WARN

Резюме не построено, звонок сохранён без него

is not saved - <причина>

WARN

Загруженный ответ не прошёл проверку и не сохранён

is marked download-failed, is marked transcription-failed

WARN

У активности установлен статус сбоя, в конце сообщения — причина

the activity of call … is gone

WARN

Активность удалена до обработки аудиозаписи, аудиозапись отброшена

has no activity, the status … is not written

WARN

Статус сбоя некуда записать: активности нет

could not be marked

WARN

Не удалось записать статус сбоя в активность

could not be saved, one more attempt follows

WARN

Первая попытка сохранить результат не удалась, через 5 секунд будет вторая

could not be saved into its activity

WARN

После исчерпания повторов не удалось сохранить mp3-файл, резюме или текст (указано в сообщении); остальное сохраняется

the temporary file … could not be deleted

WARN

Временный файл аудиозаписи не удалён после записи и остался в хранилище; на обработку звонка не влияет

its card link could not be added

WARN

Активность создана без ссылки на карточку звонка

the retryHttpStatuses entry … is not a number

WARN

Ошибка в параметре retryHttpStatuses, значение пропущено

the failure of call … is temporary

WARN

Ошибка признана временной и будет повторена

is not transcribed

ERROR

Распознавание окончательно не удалось, аудиозапись сохранена без текста

failed with HTTP N

ERROR

Ошибка обращения к внешнему сервису с кодом ответа

failed [<тип ошибки>], full stack trace, response body

ERROR

Подробности ошибки: тип, стек вызовов, тело ответа внешнего сервиса

is LOST

ERROR

Уведомление не удалось записать в очередь; следующее сообщение лога содержит его для ручного восстановления

Для HTTP 404 скачивания Mango действует отдельная ветка: обычная строка the failure of call … is temporary может отсутствовать, хотя повтор назначен. Проверяйте специальное предупреждение о 404, scheduled for retry и очереди mango-recordings-retry-*. HTTP 404 от STT этим правилом не охватывается.

Очереди недоставленных сообщений

В очереди недоставленных сообщений (DLQ, dead letter queue) попадают сообщения, которые не удалось обработать после всех повторов. Автоматически эти очереди не разбираются.

Очередь

Что в неё попадает

mango-events-dlq

Уведомления, которые не удалось обработать: поиск сделки или лида, создание лида или активности

mango-recordings-dlq

Звонки, аудиозапись которых не удалось загрузить, распознать или сохранить после всех повторов

Звонки с неудачной обработкой аудиозаписи можно найти по атрибуту recording-aspect:recordingStatus активностей со значениями download-failed и transcription-failed или по сообщениям is marked в логе. В поставке нет готового фильтра журнала активностей по статусу обработки аудиозаписи. Звонки с неоднозначной привязкой находятся по маркеру [mango:ambiguous] в тексте активности (поле «Примечание» карточки звонка).

Восстановление из очереди недоставленных

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

  2. Устраните причину: восстановите сервис распознавания или Records API, исправьте конечную точку либо доступ к MANGO OFFICE. Убедитесь, что маршрут запущен и у целевой очереди есть потребитель.

  3. Опубликуйте исходное тело в exchange mango-call-recordings с соответствующим routing key. Используйте persistent-сообщение и подтвердите успешную маршрутизацию и публикацию до удаления исходного сообщения из очереди недоставленных.

    Исходная очередь

    Routing key

    mango-events-dlq

    mango-events

    mango-recordings-dlq

    mango-recordings

  4. Для нового бюджета повторов обработки аудиозаписи удалите заголовок mango-recording-retry-attempt. Перемещение сообщения с сохранением этого заголовка не сбрасывает бюджет. Не меняйте entryId, recordingId и ссылки на активность в JSON.

  5. После подтверждённой публикации удалите исходное сообщение из очереди недоставленных. Не очищайте всю очередь командой Purge.

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

Предупреждение

При ручной работе через Management UI не выполняйте одновременно несколько переносов одного сообщения. Для массового восстановления нужен контролируемый инструмент с подтверждениями публикации и учётом уже перенесённых сообщений. Обычный перенос через Shovel («Move messages») не следует считать сбросом счётчика повторов: отдельно проверьте заголовки.

Если ошибка постоянная и сообщение было успешно обработано со статусом ошибки, в очереди недоставленных его может не быть. После исправления причины требуется повторная подача исходного уведомления или сохранённого сообщения (см. Повторная загрузка аудиозаписи отдельного звонка), а не только изменение статуса в карточке.

Если уведомление было потеряно при первичной публикации (ошибка is LOST), следующее сообщение лога содержит уже готовый JSON-объект для очереди с полями webhookId и body. Скопируйте этот объект целиком, без префикса строки лога, и опубликуйте в exchange mango-call-recordings с routing key mango-events. Не вкладывайте всю оболочку повторно в поле body. Формат объекта:

{"webhookId":"mango-webhook","body":"<содержимое уведомления>"}

Если уведомления нет ни в очередях, ни в логах, возврат из очереди недоставленных невозможен — сначала необходимо получить исходные данные звонка.

Повторная загрузка аудиозаписи отдельного звонка

MANGO OFFICE не отправляет уведомления повторно, поэтому уведомление о записи можно подать вручную. Это нужно в трёх случаях:

  • у активности статус download-failed или transcription-failed, а сообщения этого звонка в очереди недоставленных нет;

  • уведомление о записи пришло раньше итога вызова и было отброшено;

  • итог вызова вручную возвращён из mango-events-dlq, а уведомление о записи к этому времени уже было отброшено.

Порядок действий
  1. Определите идентификатор звонка entry_id: это часть значения поля «Идентификатор звонка в телефонии» (recording-aspect:meetingUrl) после mango://entry/.

  2. Определите идентификатор аудиозаписи recording_id. В карточке звонка он не хранится. Найдите его в логе по entry_id в сообщении Mango: the recording <recording_id> of call <entry_id> is queued for … либо получите через API статистики вызовов MANGO OFFICE (поле records). Для уведомления, отброшенного из-за обратного порядка, recording_id в лог не выводится: получите его в MANGO OFFICE.

  3. В RabbitMQ Management опубликуйте в exchange mango-call-recordings с routing key mango-events сообщение:

    {"webhookId":"mango-webhook","body":"{\"entry_id\":\"<entry_id>\",\"recording_id\":\"<recording_id>\"}"}
    
  4. Убедитесь, что в логе появилось сообщение is queued for, затем проверьте статус обработки аудиозаписи в карточке звонка.

Звонок в статусе completed повторно не обрабатывается. Повтор возможен, только пока аудиозапись хранится в облаке MANGO OFFICE (срок зависит от тарифа). Если скачивание отвечает HTTP 404, сначала выполняются отложенные повторы, и только при исчерпании бюджета устанавливается download-failed. Перед ручной подачей убедитесь, что тот же звонок уже не ожидает в retry-очереди.

Типичные проблемы

Симптом

Возможная причина

Что сделать

Звонки не появляются в CRM, в логе нет сообщений Mango:

Маршрут остановлен или уведомления не доходят до Citeck

Проверить состояние маршрута, адрес в личном кабинете, доступность адреса с IP-адресов MANGO OFFICE

Звонки не появляются, MANGO OFFICE получает ответ 401

Неверный код ВАТС или соль в секрете mango-api

Сверить секрет с данными API-коннектора; отклонённые запросы в логе Citeck не отображаются

На каждый звонок создаётся новый лид

Поле phoneDigits отсутствует или не вычислено у существующих записей, либо статусы исключения не соответствуют модели CRM

Выполнить Шаг 1. Проверка данных CRM, проверить Правила выбора сделки или лида

Созданный лид не виден, «Нет доступа»

Пользователь не входит в группы CRM

Проверить под пользователем из группы менеджеров или администраторов CRM

Активность есть, аудиозаписи нет, статус пуст

Уведомление о записи не пришло или пришло раньше итога вызова

Проверить сохранение аудиозаписей в облако и отправку уведомлений; подать уведомление о записи вручную

Статус долго остаётся downloading

Идут отложенные повторы или сообщение попало в очередь недоставленных

Проверить лог и очереди mango-recordings-retry-* и *-dlq

После record/added скачивание отвечает HTTP 404

Файл ещё недоступен по API Mango либо отсутствует/удалён

Проверить специальное предупреждение и назначенные повторы. Не дублировать сообщение вручную, пока оно ожидает в retry-очереди; после исчерпания бюджета проверить наличие записи и mango-recordings-dlq

Статус download-failed

MANGO OFFICE не отдал аудиозапись или вернул не аудио

Проверить лог, доступность app.mango-office.ru, наличие аудиозаписи в личном кабинете

Все загрузки аудиозаписей завершаются ошибкой после смены кода ВАТС

Camel-контекст не пересоздан после изменения секрета

Остановить и запустить маршрут, вернуть сообщения из mango-recordings-dlq, для остальных звонков со статусом download-failed подать уведомление о записи вручную (см. Смена учётных данных API-коннектора)

Статус transcription-failed

Сервис распознавания недоступен или не смог распознать аудиозапись

Проверить сервис распознавания и конечную точку stt-sidecar из среды ecos-integrations. Аудиозапись в карточке доступна; расшифровку можно получить повторной подачей уведомления о записи

Текст не разделён по говорящим

У сервиса распознавания не задан HF_TOKEN

Проверить значение diarization_available в ответе /health

Нет резюме

Модуль Citeck AI не установлен или выключен

Проверить модуль Citeck AI; звонок при этом сохранён

Маршрут не запускается

Не заполнен секрет, нет конечной точки, не задан брокер или включён TLS к брокеру

Проверить лог при запуске, секрет, конечные точки и источник данных RabbitMQ