Flussonic Media Server documentation

Содержание

Events API

Cобытия Flussonic

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

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

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

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

Содержание:

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

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

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

notify log_name {
    sink log://log/crash.log;
    verbose debug;
}

Здесь:

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

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

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

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

notify log_name {
    sink log://log/crash.log;
    except media=*;
    verbose debug;
}

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

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

notify handler_name {
    sink http://backend.local/notify.php;
}

Такое объявление создаст обработчик событий с именем handler_name и он будет отсылать ВСЕ события на

HTTP URL http://backend.local/notify.php.

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

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

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

notify handler_name {
    sink http://backend.local/notify.php;
    only event=stream_started,stream_stopped,source_ready,source_lost;
}

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

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

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

sink
Получатель событий. Может быть задан HTTP URL: http://URL, https://URL или путь к LUA скрипту: path_to_lua_script.lua
<dt>only</dt>
<dd>Белый список ограничений. Можно указать несколько <code>key=value</code> или <code>key=value1,value2</code> опций для каждой строки <code>only</code>.
Вы можете фильтровать события по их типу <code>event</code>, по <code>media</code> или любому другому полю, такому как <code>country</code> или <code>ip</code>.
Обычно это event и media. Ниже есть более полное описание поведения <code>only</code>.</dd>

<dt>except</dt>
<dd>Черный список ограничений. События, совпавшие с одним из полей в <code>except</code> не будут переданы обработчику.</dd>

<dt>buffer</dt>
<dd>Не рекомендуем использовать</dd>

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

Некоторые дополнительные опции:

sign_key
Вы можете указать ключ подписи для HTTP приёмника событий. Когда Flussonic будет готовить HTTP POST запрос с данными в формате JSON, он добавит этот ключ к телу запроса, вычислит SHA1 хэш и добавит его его в hex виде в http header `X-Signature`. Это может использоваться для проверки, что событие отправил именно Flussonic.

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

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

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

  • если любая 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"}

Список доступных событий

server_started
Посылается после старта сервера
<dt>listener_start</dt>
<dd>Flussonic открыл какой-то порт на приём подключений</dd>

<dt>listener_failure</dt>
<dd>Ошибка открытия порта для приёма подключений</dd>

<dt>config_reloaded</dt>
<dd>Конфиг был перечитан</dd>

<dt>session_opened</dt>
<dd>Открытие сессии</dd>

<dt>session_closed</dt>
<dd>Закрытие сессии</dd>

<dt>file_opened</dt>
<dd>Открытие файла</dd>

<dt>file_closed</dt>
<dd>Закрытие файла</dd>

<dt>stream_started</dt>
<dd>Запуск потока</dd>

<dt>stream_stop</dt>
<dd>Поток получил команду на закрытие через API</dd>

<dt>stream_stopped</dt>
<dd>Остановка потока</dd>

<dt>stream_reconfigured</dt>
<dd>Обновление конфигурации потока</dd>

<dt>stream_motion_started</dt>
<dd>На IP камере было отмечено движение</dd>

<dt>stream_motion_stopped</dt>
<dd>На IP камере было окончено движение</dd>

<dt>source_ready</dt>
<dd>Поток принял первые кадры</dd>

<dt>stream_media_info</dt>
<dd>Свойства потока (media_info) изменились</dd>

<dt>source_lost</dt>
<dd>Источник потока потерян и требует перезапуска</dd>

<dt>source_switch</dt>
<dd>Поток переключился на другой источник</dd>

<dt>frames_timed_out</dt>
<dd>Источник потока перестал слать кадры (но ещё не перезапущен)</dd>

<dt>frames_restored</dt>
<dd>Источник потока возобновил отсылку кадров после перерыва</dd>

<dt>stream_backup</dt>
<dd>Начал проигрываться запасной файл в связи с потерей источника</dd>

<dt>publish_started</dt>
<dd>Началась публикация в поток</dd>

<dt>publish_stopped</dt>
<dd>Публикация в поток окончилась (вы можете получить много значимой информации c этим событием)</dd>

<dt>push_started</dt>
<dd>Поток начал отправку (push) на другой источник</dd>

<dt>stream_jpeg</dt>
<dd>Новый JPEG скриншот был сгенерован</dd>

<dt>dvr_new_fragment</dt>
<dd>Новый DVR фрагмент был записан на диск</dd>

<dt>dvr_deleted_fragments</dt>
<dd>Старые фрагменты были удалены из архива</dd>

<dt>dvr_new_blob</dt>
<dd>Новый часовой отрезок был открыт для записи архива</dd>

<dt>stream_force_close_gop</dt>
<dd>Ошибка потока: получена неправильная временная отметка или слишком малое количество кадров в секунду</dd>

<dt>stream_rt_sync</dt>
<dd>В потоке произошла пересинхронизация аудио и видео. Может быть признаком ошибок в потоке, если происходит слишком часто.</dd>

<dt>stream_broken_source</dt>
<dd>Поток не может быть прочитан из текущего источника и было решено перезапустить поток</dd>

<dt>dvr_replication_started</dt>
<dd>Началась репликация архива</dd>

<dt>dvr_hour_replication_started</dt>
<dd>Началась репликация часового отрезка архива</dd>

<dt>dvr_hour_replication_done</dt>
<dd>Репликация часового отрезка архива закончилась</dd>

<dt>dvr_replication_progress</dt>
<dd>Отображение процесса репликации</dd>

<dt>dvr_replication_done</dt>
<dd>Процесс репликации закончен</dd>

<dt>udp_pusher_does_not_fit_cbr</dt>
<dd>Поток, отправленный по <a href="/doc/proigryvanie/rassylka-udp-s-postoyannym-bitreytom-cbr#configuration" orig="play/cbr-udp#configuration">UDP с постоянным битрейтом</a> (через настройку потока вида <code>push udp://IP_ADDRESS?cbr=...</code>), имеет слишком высокий битрейт, что может привести к переполнению буфера. В результате может возникнуть ошибка или рестарт потока. Чтобы такого не произошло, вы можете перекодировать поток в меньший битрейт с помощью транскодера.</dd>    

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

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

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

notify no_video {
    only event=stream_stopped,source_lost;
    sink /etc/flussonic/no_video.lua;
    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 сервера необходимо указывать РЕАЛЬНОЕ доменное имя:

hostname
streamer1.my.cdn

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

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

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

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

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

notify performance_handler {
    sink http://backend.local/notify.php;
    only group=system_overloaded;
}

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

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

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

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

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

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

notify watcher {
   sink http://backend.local/notify.php;
   resend_notifications_limit 1000;
   resend_notifications_timeout 10;
}

где:

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