Events API
Cобытия Flussonic
В Flussonic Media Server есть удобная и гибкая система внутренних событий, с маршрутизацией и обработчиками, и возможностями настройки.
События инициируются в разных частях системы и могут использоваться для разных сценариев.
Чтобы задать настройки, связанные с событиями, в файл конфигурации Flussonic добавьте директиву notify и опцию sink (получатель события):
- Чтобы использовать кастомный обработчик, в
sink
нужно указать путь до него. - Чтобы записать событие в журнал событий (лог), в
sink
указывают путь к файлу журнала.
Далее укажите различные опции, чтобы отфильтровать события до того, как они попадут в лог или в обработчик.
Содержание:
- Настройка логирования событий
- Настройка обработчиков событий
- Фильтрация событий
- Список доступных событий
- Пример настройки email нотификаций
- События производительности
- Гарантированная доставка уведомлений
Настройка логирования событий
В дополнение к основному журналу, 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
- only
- Белый список ограничений. Можно указать несколько
key=value
илиkey=value1,value2
опций для каждой строкиonly
. Вы можете фильтровать события по их типуevent
, поmedia
или любому другому полю, такому какcountry
илиip
. Обычно это event и media. Ниже есть более полное описание поведенияonly
. - except
- Черный список ограничений. События, совпавшие с одним из полей в
except
не будут переданы обработчику. - buffer
- Не рекомендуем использовать
Все остальные опции в этом блоке будут переданы указанному приёмнику событий.
В 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"}
UI для настройки логирования и фильтрации событий
События можно настроить в Config > Events:
Если необходимая вам опция отсутствует среди полей на экране, вы можете настроить её в Extended.
Список событий
- server_started
- Посылается после старта сервера
- listener_start
- Flussonic открыл какой-то порт на приём подключений
- listener_failure
- Ошибка открытия порта для приёма подключений
- config_reloaded
- Конфиг был перечитан
- session_opened
- Открытие сессии
- session_closed
- Закрытие сессии
- file_opened
- Открытие файла
- file_closed
- Закрытие файла
- stream_started
- Запуск потока
- stream_stop
- Поток получил команду на закрытие через API
- stream_stopped
- Остановка потока
- stream_reconfigured
- Обновление конфигурации потока
- stream_motion_started
- На IP камере было отмечено движение
- stream_motion_stopped
- На IP камере было окончено движение
- source_ready
- Поток принял первые кадры
- stream_media_info
- Свойства потока (media_info) изменились
- source_lost
- Источник потока потерян и требует перезапуска
- source_switch
- Поток переключился на другой источник
- frames_timed_out
- Источник потока перестал слать кадры (но ещё не перезапущен)
- frames_restored
- Источник потока возобновил отсылку кадров после перерыва
- stream_backup
- Начал проигрываться запасной файл в связи с потерей источника
- publish_started
- Началась публикация в поток
- publish_stopped
- Публикация в поток окончилась (вы можете получить много значимой информации c этим событием)
- push_started
- Поток начал отправку (push) на другой источник
- stream_jpeg
- Новый JPEG скриншот был сгенерирован
- dvr_new_fragment
- Новый DVR фрагмент был записан на диск
- dvr_deleted_fragments
- Старые фрагменты были удалены из архива
- dvr_new_blob
- Новый часовой отрезок был открыт для записи архива
- stream_force_close_gop
- Ошибка потока: получена неправильная временная отметка или слишком малое количество кадров в секунду
- stream_rt_sync
- В потоке произошла пересинхронизация аудио и видео. Может быть признаком ошибок в потоке, если происходит слишком часто.
- stream_broken_source
- Поток не может быть прочитан из текущего источника и было решено перезапустить поток
- dvr_replication_started
- Началась репликация архива
- dvr_hour_replication_started
- Началась репликация часового отрезка архива
- dvr_hour_replication_done
- Репликация часового отрезка архива закончилась
- dvr_replication_progress
- Отображение процесса репликации
- dvr_replication_done
- Процесс репликации закончен
- udp_pusher_does_not_fit_cbr
- Поток, отправленный по [UDP с постоянным битрейтом](../proigryvanie/rassylka-udp-s-postoyannym-bitreytom-cbr.md#play-cbr-udp-page) (через настройку потока вида
push udp://IP_ADDRESS?cbr=...
), имеет слишком высокий битрейт, что может привести к переполнению буфера. В результате может возникнуть ошибка или рестарт потока. Чтобы такого не произошло, вы можете перекодировать поток в меньший битрейт с помощью транскодера.
Пример настройки 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 будет пытаться отослать события.