Дмитрий Кайдаш
01.06.2020
4402

Демон парсинга ami-событий звонка

Описание: очень часто вслед за установкой собственной АТС возникает необходимость отслеживать количество принятых, пропущенных и переведённых звонков, а также передавать события во внешнюю систему, например, CRM.. Это достигается за счёт покупки и установки различных систем статистики, а также приложений мониторинга. Каждый из них использует два возможные подхода: разбор хранимых данных (логи, база данных) или же […]

Описание: очень часто вслед за установкой собственной АТС возникает необходимость отслеживать количество принятых, пропущенных и переведённых звонков, а также передавать события во внешнюю систему, например, CRM.. Это достигается за счёт покупки и установки различных систем статистики, а также приложений мониторинга. Каждый из них использует два возможные подхода: разбор хранимых данных (логи, база данных) или же работа в реальном времени (AMI, ARI, оповещения из dialplan). О мониторинге в реальном времени мы сегодня и поговорим.

Все инструкции тестировались на следующем оборудовании:

  1. CentOS Linux release 7.5.1804
  2. Asterisk 13.22.0
  3. PHP 5.6.38
  4. Apache/2.4.6
Внимание! Работа на других версиях не гарантируется. Под версию php ниже 5.4 необходимо будет произвести некоторые изменения, но работоспособность не пострадает.
Внимание! Версия asterisk не критична, однако описание справедливо для дистрибутивов PBX, а не собранных из сорцов, поскольку могут отличаться контексты.

Статья описывает общие положения об анализе потока AMI-событий и может быть реализована на любом доступном вам языке программирования. Для написания демонстрационного примера был использован PHP, как наиболее простой и распространенный вариант. Что следует уметь делать демону:

  1. Переходить в фоновый режим
    1. Избегать вывода в консоль
      1. Подключаться к ami-сокету и получать из него данные
  1. Формировать из потока конвейер событий
  2. В зависимости от наличия события и его аргументов выполнять необходимые действия

Некоторые пояснения

Переход в фоновый режим подразумевает, что ни мы — пользователи — ни сама система не будут иметь прямого воздействия на демон. А так же после старта управление будет возвращено основному потоку. В большинстве ЯП для этого есть специальный оператор fork, который разделяет процесс на два: родительский и дочерний.

Вывод в консоль заменяется обработчиком ошибок и логированием, поскольку у демона попросту нет возможности использовать общий поток ввода\вывода.

Подключение к ami-сокету является основой работы демона и, фактически третью всего его функционала. Заключается в подключении и удержании соединения на локальном хосту 127.0.0.1 и порту 5038. Данные для прохождения авторизации, а также способы их создания будут рассмотрены позже. После прохождения подключения и получения доступа к данным, нам остаётся постоянно и полностью их выгружать.

Конвейер событий — заслуживает отдельного упоминания и является второй третью функционала. Поскольку данные из сокета не имеют чёткой структуры, и получаются в виде набора текста (строки), то эту структуру ещё предстоит создать и заполнить. А именно представить данные в виде массива. Признаками разделения можно считать:

  • двойной символ “\r\n\r\n” — разделитель между блоками событий
  • одинарный символ “\r\n” — разделитель строк внутри события
  • первое наличие в строке символа «:» — разделитель ключа и его значения

Заключительная третья часть демона — это разбор получившегося массива данных и соответствующая на них реакция. Это может быть как выполнение каких-то действий непосредственно на АТС в реальном времени, так и передача данных на сторону удалённого сервера в целях сбора статистики.

Предположим у нас есть некий скрипт, который оповещает систему о наступлении событий звонка:

  • начало
  • ответ\сброс
  • завершение

Для установки и настройки нам потребуется доступ на АТС посредством SSH. Точнее в консоль через клиент PuTTy или аналогичный и какой-либо файлообменник. Для примера мы воспользуемся WinSCP.

Первым делом подключаемся и размещаем демона в корневой web-директории следующим образом

Размещение скрипта-демона
Внимание! Поскольку в данном случае исполнять наш скрипт будет НЕ web-сервер, а сам интерпретатор php, рассчитывать на какой-либо вывод и отображение в браузере не приходится, однако у нас остаётся логирование. По этой же причине нет необходимости менять на скрипт права, владельца или делать его исполнимым.

Следующее, что нам нужно, это разместить bash скрипт-контроллер в нужной директории.

Размещение скрипта-контроллера

Здесь уже несколько иные условия, поэтому нам нужно сделать скрипт исполняемым. Достичь этого можно командой:

# chmod a+x /etc/init.d/callwatch
Даём права на исполнение

Возвращаемся к демону и копируем абсолютный путь к нему. Для этого можно использовать средства программы-файлообменника.

Абсолютный путь к демону

Скопированную строку нужно заменить в контроллере, как показано на скриншоте ниже.

Настройка пути в контроллере

Здесь же можно ознакомиться с примером примитивного скрипта-контроллера в полном объёме.

#!/bin/bash
#
# <CallWatch>
# 

# functions
start(){
	echo -n "Try to start <CallWatch>..." && /usr/bin/php -f /var/www/html/voxapp/callwatch.php && echo "successful"
}

stop(){
	echo -n "Try to stop <CallWatch>..." && kill -9 $( ps aux | grep "[c]allwatch.php" | awk '{print $2}' ) && echo "successful"
}

status(){
	process=$( ps aux | grep "[c]allwatch.php" )
	if [[ "$process" = "" ]]; then
		echo "CallWatch is dead"
	else
		echo "CallWatch is alive"
	fi
}

restart(){
	stop
	start
}

# controller
case "$1" in
	start)		start;;
	stop)		stop;;
	status)		status;;
	restart)	restart;;
	*)		echo "Use: $0 {start|stop|status|restart}"
esac

Последнее что нам следует сделать, перед переходом к полевым испытаниям, это добавить пользователя AMI и указать доступы в демоне. Сделать это можно двумя способами: через интерфейс FreePBX или же консоль. Рассмотрим оба варианта.

В первом, заходим на web-интерфейс и открываем следующую страницу.

Вкладка создания ami-пользователя

После чего добавляем нового пользователя и настраиваем его данные:

Manager name — логин, под которым мы будем авторизоваться в системе

Manager secret — соответственно, пароль

Deny  — подсети из которых запрещено обращаться

Permit — подсети разрешенные для обращений

Write Timeout — ожидание ответа

Настройки ami-пользователя

И ещё нам нужно ограничить нашего пользователя в правах на чтение\запись данных. Переходим на соседнюю вкладку «permissions». И выставляем всё как показано ниже:

Права ami-пользователя

Права на запись нам не нужны, поскольку демон только слушает и парсит события. Но и все события слушать нет нужды, нам нужно знать только статусные события звонка. После применения настроек («submit»+»apply») возвращаемся к демону и прописываем в нём настройки, которые мы указали ранее:

// Данные подключения
define('AMI_HOST','127.0.0.1');
define('AMI_PORT','5038');
define('AMI_USER','custommanager');
define('AMI_PASS','169*******************836');
define('LINK', 'https://domain.crm.ru/services/ats/');

Если у вас используется стандартный дистрибутив, то первые две строки менять не нужно. Третья и четвертая, соответственно, логин и пароль ami-пользователя. Пятая, здесь и далее, ссылка на внешний хост на котором располагается приемник событий. Это может быть CRM или база данных.

Второй способ создания ami-пользователя — через консоль. Подключаемся к АТС и открываем на редактирование файл:

# nano /etc/asterisk/manager_custom.conf

И добавляем в конец следующие строки:

[custommanager]
secret = 169*******************836
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
read = call
write =
writetimeout = 100
Внимание! Ни в коем случае не редактируйте другие файлы. Особенно с без приписок или с припиской "_additional" эти файлы редактируются исключительно посредством FreePBX.
Ручное создание ami-пользователя

После чего открываем консоль CLI и выполняем следующие команды для перечитывания настроек и проверки наличия нового пользователя:

# asterisk -rvvvv
> manager reload
> manager show users

Если всё выполнено правильно вне зависимости от способа добавления мы должны получить следующее:

Проверка наличия нового ami-пользователя

Собственно на этом установка и настройка завершена, можем переходить к испытаниям.

Выполним ряд команд управления демоном посредством контроллера:

# service callwatch status
Внимание! При базировании на centOS старше 7го используется измененный синтаксис:
# systemctl [start|stop|restart|status] callwatch.service

Если ранее инструкции были выполнены без ошибок мы должны получить оповещение о том, что демон неактивен.

Демон неактивен

Выполним его запуск и проверим успешно ли процесс перейдет в фоновый режим.

# service callwatch start
# ps aux | grep [c]allwatch.php
Запуск и проверка процесса

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

# cd
# ls -l /callwatch.log
# cat /callwatch.log
Лог демона

Если вы видите что-то похожее значит демон запущен, процесс успешно перешёл в фоновый режим, создал файл лога и обозначил дату и время своего запуска. Теперь можно поставить файл лога на постоянный вывод командой tailf и совершить несколько звонков\переводов для проверки работы отлова событий звонка.

Следует отметить, что ротация лога не предусмотрена и поэтому следует назначить его очистку, либо запланировать перезапуск демона. Например это можно сделать дописав в штатный планировщик cron рестарт в нерабочее время АТС.  Для этого выполняем команду:

# crontab -e

И дописываем в конец файла строку:

# 00 06 * * * /etc/init.d/callwatch restart > /dev/null 2>&1

Инструкции по планировщику легко найти в интернете, поэтому останавливаться на них не будем. Заметим лишь, что в примере указано выполнить перезапуск в 06:00 по времени сервера.

Размещение команды на перезапуск в планировщике

Вывод: таким образом нам удалось настроить оповещение внешней системы о событиях вызова:

  1. начало
  2. ответ\сброс
  3. завершение
  4. перевод (управляемый и слепой)
Характеристика анализа потока AMI-событий для реализации на любом доступном языке программирования.

Подписаться
Уведомление о
guest
2 Комментарий
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Denis
Denis
16.06.2020 22:06

А где же сам скрипт?

Дмитрий
Дмитрий
17.06.2020 10:22
Reply to  Denis

Здравствуйте.
Статья описывает технические принципы и последовательность шагов чтобы технический специалист мог написать собственного демона под конкретную задачу и не предполагает наличие готового скрипта

Last edited 3 месяцев назад by Дмитрий

Остались вопросы?

Я - Компаниец Никита, менеджер компании Voxlink. Хотите уточнить детали или готовы оставить заявку? Укажите номер телефона, я перезвоню в течение 3-х секунд.

VoIP оборудование

ближайшие курсы

ближайшие Вебинары

ONLINE

10 доводов в пользу Asterisk

Распространяется бесплатно.

Asterisk – программное обеспечение с открытым исходным кодом, распространяется по лицензии GPL. Следовательно, установив один раз Asterisk вам не придется дополнительно платить за новых абонентов, подключение новых транков, расширение функционала и прочие лицензии. Это приближает стоимость владения станцией к нулю.

Безопасен в использовании.

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

Надежен в эксплуатации.

Время работы серверов некоторых наших клиентов исчисляется годами. Это значит, что Asterisk работает несколько лет, ему не требуются никакие перезагрузки или принудительные отключения. А еще это говорит о том, что в районе отличная ситуация с электроэнергией, но это уже не заслуга Asterisk.

Гибкий в настройке.

Зачастую возможности Asterisk ограничивает только фантазия пользователя. Ни один конструктор шаблонов не сравнится с Asterisk по гибкости настройки. Это позволяет решать с помощью Asterisk любые бизнес задачи, даже те, в которых выбор в его пользу не кажется изначально очевидным.

Имеет огромный функционал.

Во многом именно Asterisk показал какой должна быть современная телефонная станция. За многие годы развития функциональность Asterisk расширилась, а все основные возможности по-прежнему доступны бесплатно сразу после установки.

Интегрируется с любыми системами.

То, что Asterisk не умеет сам, он позволяет реализовать за счет интеграции. Это могут быть интеграции с коммерческими телефонными станциями, CRM, ERP системами, биллингом, сервисами колл-трекинга, колл-бэка и модулями статистики и аналитики.

Позволяет телефонизировать офис за считанные часы.

В нашей практике были проекты, реализованные за один рабочий день. Это значит, что утром к нам обращался клиент, а уже через несколько часов он пользовался новой IP-АТС. Безусловно, такая скорость редкость, ведь АТС – инструмент зарабатывания денег для многих компаний и спешка во внедрении не уместна. Но в случае острой необходимости Asterisk готов к быстрому старту.

Отличная масштабируемость.

Очень утомительно постоянно возвращаться к одному и тому же вопросу. Такое часто бывает в случае некачественного исполнения работ или выбора заведомо неподходящего бизнес-решения. С Asterisk точно не будет такой проблемы! Телефонная станция, построенная на Asterisk может быть масштабируема до немыслимых размеров. Главное – правильно подобрать оборудование.

Повышает управляемость бизнеса.

Asterisk дает не просто набор полезных функций, он повышает управляемость организации, качества и комфортности управления, а также увеличивает прозрачность бизнеса для руководства. Достичь этого можно, например, за счет автоматизации отчетов, подключения бота в Telegram, санкционированного доступа к станции из любой точки мира.

Снижает расходы на связь.

Связь между внутренними абонентами IP-АТС бесплатна всегда, независимо от их географического расположения. Также к Asterisk можно подключить любых операторов телефонии, в том числе GSM сим-карты и настроить маршрутизацию вызовов по наиболее выгодному тарифу. Всё это позволяет экономить с первых минут пользования станцией.