Events API

События Flussonic

Во Flussonic Media Server есть удобная и гибкая система внутренних событий с маршрутизацией, обработчиками и возможностями настройки. Данная статья описывает, как настроить Flussonic для фильтрации и отправки событий. Подробнее прочитать про работу сессий стриминга можно в отдельной статье.

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

Чтобы задать настройки, связанные с событиями, в файл конфигурации Flussonic добавьте директиву event_sink и опцию url (получатель события):

• Чтобы использовать кастомный обработчик, в url нужно указать путь до него.
• Чтобы записывать события в журнал событий (лог), в url указывают путь к файлу журнала.

Далее укажите различные опции, чтобы отфильтровать события до того, как они попадут в лог или в обработчик.

Содержание:

• Настройка логирования событий
• Настройка обработчиков событий
• Фильтрация событий
• Список доступных событий
• Пример настройки email нотификаций
• События производительности
• Гарантированная доставка уведомлений

Настройка логирования событий

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

Чтобы вести свой файл с журналом событий, добавьте директиву event_sink и укажите путь к файлу журнала в опции url log://:

event_sink log_name {
    url log:///var/log/flussonic/crash.log;
    verbose debug;
}

Здесь:

• log_name — просто название настройки. Для удобства можно давать содержательные названия.
• url — получатель событий. В случае логов это файл, в который нужно записывать информацию о событиях.
• verbose — уровень логирования по степени важности событий. debug (самое подробное логирование), info, или alert (логирование только важных событий), notice, warning, error, critical.

Исключение событий из лога

Чтобы не записывать определенные события в данный файл, перечислите их в опции except.

Например, следующая конфигурация игнорирует события, касающиеся потоков (но пишет другие события, такие как события сервера Flussonic):

event_sink log_name {
    url log:///var/log/flussonic/events.log;
    except media=*;
    verbose debug;
}

Настройка обработчиков событий

Каждый обработчик должен быть объявлен в конфигурации:

event_sink handler_name {
    url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
}

Такое объявление создаст обработчик событий с именем handler_name и он будет отсылать все события на HTTP URL http://backend.local/notify.php.

В этой конфигурации все события Flussonic Media Server будут отправляться в JSON-формате как список объектов.

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

Мы можем уменьшить поток событий улучшив конфигурацию:

event_sink handler_name {
    url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
    only event=stream_opened,stream_closed,source_opened,source_closed;
}

С такой конфигурацией на этот обработчик будут отправляться только определённые события.

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

В конфигурации обработчика событий можно указать следующие опции:

Все остальные опции в этом блоке будут переданы указанному приёмнику событий. В LUA-скрипте они доступны в таблице args. По HTTP они передаются вместе с другими параметрами.

Фильтрация событий

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

Правила фильтрации:

• если любая except директива полностью совпала с событием, событие выкидывается и не передаётся в обработчик;
• если в объявлении обработчика нет only директив, события передаются в обработчик;
• если директивы only есть, то событие передается в обработчик, если оно полностью совпало хотя бы с одной директивой only.

Полное совпадение директивы с событием означает, что все пары "ключ=значение" в директиве равны значениям в событии. Если в директиве указано "ключ=значение1,значение2,значение3", то это означает, что поле "ключ" в событии должно быть равным какому-то одному значению из заданного списка.

Примеры:

• only event=stream_started; совпадает с {event: "stream_started", media: "cbc"}
• only event=stream_started,stream_stopped; совпадает с {event: "stream_started", media: "cbc"}
• only event=stream_started,stream_stopped media=tnt; не совпадает с {event: "stream_started", media: "cbc"}
• only event=stream_started media=cbc group=news; не совпадает с {event: "stream_started", media: "cbc"}

UI для настройки логирования и фильтрации событий

События можно настроить в Config > Events:

Если необходимая вам опция отсутствует среди полей на экране, вы можете настроить её в Extended.

Список событий

Здесь перечисены некоторые популярные события. Вы можете найти описани других событий в схеме API (см. параметр ответа events).

Пример настройки email нотификаций

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

Простейшая конфигурация будет выглядеть так:

event_sink no_video {
    url lua:///etc/flussonic/no_video.lua;
    only event=stream_stopped,source_closed;
    from flussonic@streamer1.my.cdn;
    to admin@my.cdn;
    via smtp://127.0.0.1:587;
}

Этой конфигурации достаточно, если вы не хотите фильтровать события по определённым потокам.

Скрипт no_video.lua:

body = "Source lost on following streams: \n"

for _, event in pairs(events) do
    body = body.."  "..event.media.."\n"
end

mail.send({from = args.from, to = args.to, subject = "Source lost", body = body})

Для корректной отправки почты необходимо установить утилиту sendmail:

apt-get install sendmail

Дополнительно необходимо убедиться, что что sendmail слушает порт, указанный в файле конфигурации:

netstat -lntp
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name          
tcp        0      0 127.0.0.1:587           0.0.0.0:*               LISTEN      3507/sendmail

В качеcтве hostname сервера необходимо указывать реальное доменное имя:

streamer1.my.cdn

События производительности

Система событий Flussonic позволяет настроить оповещения об использовании ресурсов и проблемах с производительностью.

События busy_port, busy_dist_port, long_gc, long_schedule_pid и long_schedule_port соответствуют событиям системного монитора в Erlang. Их подробное описание, условия появления и передаваемые в событии параметры находятся в документации Erlang. Эти события говорят о возможном наличии проблем с производительностью.

У Flussonic все эти события принадлежат к группе system_overloaded. Группу событий следует указывать, используя ключевое слово group.

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

event_sink performance_handler {
    url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
    only group=system_overloaded;
}

В этом примере фильтр group=system_overloaded пропускает в обработчик только события о проблемах производительности.

Использование памяти

Событие memory_usage возникает при повышенном использовании памяти. В событии передаются параметры total и used — это общий и используемый размер памяти в байтах. Flussonic отсылает событие memory_usage, когда использует более половины всей памяти. При превышении порога в 80%, событие получает дополнительно признак system_overloaded и отсылается вместе с событиями группы system_overloaded.

Гарантированная доставка уведомлений

Чтобы не терять неотправленные уведомления, можно настроить Flussonic на отложенную повторную отправку. Если принимающий HTTP сервер или скрипт не отвечает, Flussonic накапливает события в специальном буфере и периодически повторяет попытки отослать нотификации. Когда принимающий сервер начнёт отвечать, Flussonic дошлёт накопленные нотификации.

Для этого вы должны указать в конфиге две опции:

event_sink watcher {
   url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
   resend_notifications_limit 10;
   resend_notifications_timeout 10;
}

где:

• resend_notifications_limit — количество последних событий, которое будет храниться с целью повторных попыток отослать их. Не может превышать 2000.
• resend_notifications_timeout — интервал времени в секундах, через который Flussonic будет пытаться отослать события.

Мониторинг потоков RTSP

Эта группа событий сообщает о поврежденном потоке RTSP:

Ниже представлен пример конфигурационного файла:

event_sink media_info {
  url log:///var/log/flussonic/media_info.log;
  only event=stream_media_info,source_started,source_closed,stream_broken_source,rtsp_resync,rtsp_desync,rtsp_broken_data;
  verbose debug;
}

Сбор данных о рекламе

Вы можете использовать событие ad_injected для сбора информации о вставке и проигрывании рекламы в потоках. Каждый раз, когда в проигрываемый поток вставляется реклама, Flussonic генерирует это событие с такими параметрами как DTS первого кадра рекламы, путь к рекламным файлам, тип рекламного ролика и его продолжительность. Более подробную информацию смотрите в схеме API (выберите ad_injected в параметре events ответа).

Это событие записывается в лог Flussonic, позволяя отследить, сколько рекламы показал Flussonic и кому.