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;
}
С такой конфигурацией на этот обработчик будут отправляться только определённые события.
Вызовы обработчика происходят синхронно: событие не будет отправлено в обработчик, пока он не завершит обработку предыдущей порции событий.
В конфигурации обработчика событий можно указать следующие опции:
Опция | Описание |
---|---|
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 |
(Дополнительно) Вы можете указать ключ подписи для HTTP-приёмника событий. Когда Flussonic будет готовить HTTP POST запрос с данными в формате JSON, он добавит этот ключ к телу запроса, вычислит SHA1 хэш и добавит его в hex-виде в HTTP header X-Signature . Это может использоваться для проверки, что событие отправил именно Flussonic. |
Все остальные опции в этом блоке будут переданы указанному приёмнику событий.
В LUA-скрипте они доступны в таблице args
.
По HTTP они передаются вместе с другими параметрами.
Фильтрация событий
Вы можете фильтровать события перед тем, как они попадают в обработчик. Это очень важный механизм, попробуйте его использовать, потому что он уменьшает нагрузку на ваш обработчик событий. Каждое событие проходит через фильтр непосредственно в треде, создавшем это событие, перед тем, как попасть в обработчик.
Правила фильтрации:
- если любая
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"}
UI для настройки логирования и фильтрации событий
События можно настроить в Config > Events:
Если необходимая вам опция отсутствует среди полей на экране, вы можете настроить её в Extended.
Список событий
Здесь перечисены некоторые популярные события. Вы можете найти описани других событий в схеме API (см. параметр ответа events
).
События | Описание |
---|---|
ad_injected |
Advertisement was injected into the played video. |
config_reloaded |
Configuration is reloaded. |
dvr_mp4_export_aborted |
MP4 file export from DVR archive has been aborted. |
dvr_mp4_export_failed |
MP4 file export from DVR archive failed. |
dvr_mp4_export_ready |
MP4 file exported successfully from DVR archive. |
dvr_mp4_export_start |
Start of the MP4 file export from DVR archive. |
dvr_new_fragment |
Next fragment of the DVR archive was stored on disk. |
dvr_deleted_fragments |
Outdated fragments were purged from the DVR archive. |
dvr_new_blob |
One-hour interval is opened for storing the video on the DVR archive. |
dvr_replication_started |
DVR replication has started. |
dvr_hour_replication_started |
Replication of a DVR one-hour interval has started. |
dvr_hour_replication_done |
Replication of a DVR one-hour interval is completed. |
dvr_replication_progress |
DVR replication is in progress. |
dvr_replication_done |
DVR replication is completed. |
epg_changed |
EPG is updated. |
file_opened |
File is opened. |
file_closed |
File is closed. |
frames_timed_out |
Source of the stream stopped sending frames (but it has not restarted yet). |
frames_restored |
Source of the stream resumes sending frames. |
listener_start |
Flussonic starts listening on specified port. |
listener_failure |
Flussonic failed to listen on a specified port. |
play_opened |
Connection between the server and the client has been opened for the stream playback. |
play_connected |
Connection between the server and the client has been established for the stream playback. |
play_started |
Stream is being played. |
play_closed |
Stream playback stopped and session closed. |
push_opened |
Connection between the server and the client has been opened for pushing the stream. |
push_connected |
Connection between the server and the client has been established for pushing the stream. |
push_started |
Stream is being pushed. |
push_closed |
Stream stopped being pushed and session closed. |
reboot_on_upgrade |
Finishing Flussonic update and restarting. |
scte35 |
SСTE-35 marker is found. |
server_started |
Server has started. |
source_opened |
Connection between the server and the client has been opened for publishing the stream or ingesting it. |
source_connected |
Connection between the server and the client is established for publishing the stream or ingesting it. |
source_started |
Stream has received first video frames from an active source (This event is invoked for ingest, publish and file kinds of sources). |
source_closed |
Stream source is considered to be lost. |
source_switch |
Stream has switched to another source. |
stream_opened |
Stream has started. |
stream_reconfigured |
Stream configuration was updated. |
stream_stop |
Stream has received the command to stop via API. |
stream_media_info |
Stream attributes (media_info) were changed. |
stream_backup |
Backup file started playing while the source is lost. |
stream_jpeg |
New JPEG thumbnail is generated. |
stream_force_close_gop |
Stream error: invalid timestamps are coming or FPS is too low. |
stream_rt_sync |
Stream timestamps are resynced (this might be the indication of stream errors if happens too often). |
stream_broken_source |
Flussonic failed to read the stream from the source and restarted the stream. |
udp_pusher_does_not_fit_cbr |
Specified constant bitrate value of the pushed UDP stream is too high. |
web_request |
Flussonic DVR bandwidth usage data is being requested. |
Пример настройки email нотификаций
Давайте узнаем, что вы можете делать с помощью системы событий. Например, вы хотите получать письма, если поток остановился.
Простейшая конфигурация будет выглядеть так:
event_sink no_video {
url lua:///etc/flussonic/no_video.lua;
only event=stream_closed,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:
События | Описание |
---|---|
rtsp_desync |
аудио- и видеопотоки не синхронизированы |
rtsp_resync |
синхронность потоков восстановлена |
rtsp_broken_data |
Во Flussonic поступают повреждённые данные |
Ниже представлен пример конфигурационного файла:
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 и кому.