Events API для управления событиями

События Flussonic

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

Подробнее прочитать про работу сессий стриминга можно в отдельной статье.

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

Задать настройки, связанные с событиями, можно на странице Config -> Events или в файле конфигурации Flussonic с помощью директивы event_sink.

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

Опция Sink (в конфигурационном файле — url) определяет получателя событий:

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

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

Содержание:

Настройка логирования событий
Настройка обработчиков событий
Фильтрация событий
Гарантированная доставка уведомлений

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

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

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

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

Основные настройки:

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

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

Flussonic может отправлять события любому получателю, которого вы укажете в параметре Sink (url). Это может быть путь к файлу скрипта, URL удаленного обработчика и т.п. Пример:

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-формате как список объектов.

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

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

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

Опция	Описание
`url`	Получатель событий. Может быть задан HTTP URL: `http://URL`, `https://URL` или путь к LUA-скрипту: `path_to_lua_script.lua`.
`only`	Белый список ограничений. Можно указать несколько `key=value` или `key=value1,value2` опций для каждой строки `only`. Вы можете фильтровать события по их типу `event`, по `media` или любому другому полю, такому как `country` или `ip`. Обычно это `event` и `media`. Ниже есть более полное описание поведения `only`.
`except`	Черный список ограничений. События, совпавшие с одним из полей в `except` не будут переданы обработчику.
`buffer`	Не рекомендуется к использованию.
`sign_key`	(Указывается в разделе Extended (`extra`)) Вы можете указать ключ подписи для HTTP-приёмника событий. Когда Flussonic будет готовить HTTP POST запрос с данными в формате JSON, он добавит этот ключ к телу запроса, вычислит SHA1 хэш и добавит его в hex-виде в HTTP header `X-Signature`. Это может использоваться для проверки, что событие отправил именно Flussonic.

Все остальные опции в этом блоке будут переданы указанному приёмнику событий. Список доступных опций см. в описании метода API: PUT /streamer/api/v3/event_sinks/{name}. В LUA-скрипте они доступны в таблице args. По HTTP они передаются вместе с другими параметрами.

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

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

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

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

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

Примеры:

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

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

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

Пример конфигурации, которая пропускает только некоторые события

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

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

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

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

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

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

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

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

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

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