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

Описание: очень часто вслед за установкой собственной АТС возникает необходимость отслеживать количество принятых, пропущенных и переведённых звонков, а также передавать события во внешнюю систему, например, 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

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

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

2. Формировать из потока конвейер событий
3. В зависимости от наличия события и его аргументов выполнять необходимые действия

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

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

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

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

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

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

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

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

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

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

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

Следующее, что нам нужно, это разместить 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-интерфейс и открываем следующую страницу.

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

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

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

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

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

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

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

Права на запись нам не нужны, поскольку демон только слушает и парсит события. Но и все события слушать нет нужды, нам нужно знать только статусные события звонка. После применения настроек («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

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

# asterisk -rvvvv
> manager reload
> manager show users

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

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

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

# service callwatch status

# 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. перевод (управляемый и слепой)