Manage Events With API
Events in Flussonic
Flussonic has a system of internal events with routing and handling, and convenient and flexible tools to configure it. This page describes how to configure Flussonic to filter and send events, read more details about sessions events.
Events are initiated in different parts of the system and can be used in different scenarios.
To configure event-related settings, add the event_sink
directive into the Flussonic configuration file. In the url
option of this directive, define the receiver of events:
- To use your custom handler, specify the path to the handler in
url
. - To write events to a log file, specify the path to the file in
url
.
Then use various options to filter events before they come to a handler or log.
Table of contents:
- Configuring event logging
- Configuring event handlers
- Event filtering
- The list of available events
- Examples of configuring email notifications
- Performance-related events
- Reliable delivery of event notifications
Configuring event logging
In addition to the main log, Flussonic allows you to create as many log files as you need and to log events according to your filtering settings.
To write events to a custom file, add the event_sink
directive and use the url log://
option to specify the file, for example:
event_sink log_name {
url log:///var/log/flussonic/crash.log;
verbose debug;
}
Where:
- log_name — just the setting's name. It's good to give it a meaningful name.
- url — the file where event information is logged.
- verbose — the level of logging according to event importance. Can be
debug
(the most detailed logging),info
,alert
(only serious events),notice
,warning
,error
,critical
.
Excluding events from logs
To exclude some types of events, use the except
option.
For example, the following configuration will not write to the log all events concerning streams (and write other events, such as Flussonic server events):
event_sink log_name {
url log:///var/log/flussonic/events.log;
except media=*;
verbose debug;
}
Configuring event handlers
Each event handler can be declared in config:
event_sink handler_name {
url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
}
Such configuration creates an event handler with the name handler_name
and it sends all the events to HTTP URL http://IP-ADDRESS:PORT/SCRIPT_NAME.php
.
In this configuration all Flussonic events will be send in JSON format as a list of objects. On a high loaded system it can generate enormous amount of events most of which are not required.
We can reduce event traffic by better configuration:
event_sink handler_name {
url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
only event=stream_opened,stream_closed,source_opened,source_closed;
}
This configuration will send only four specific events to this handler.
Event handler calls are synchronous: an event will not be sent to the handler if the handler hasn't handled the previous event batch.
The event configuration block supports the following configuration options:
Option | Description |
---|---|
url |
The specification of the handler. It can be http://URL , https://URL , path_to_lua_script.lua |
only |
The white list of limitations. You can specify several key=value or key=value1,value2 options on each only line. You can filter events by their event field, by media field or any other like country or ip . Usually it is event and media . You should read more explicit explanation of this only behaviour. |
except |
The black list of limitations. Events matched by any of except fields will not be passed to handler. |
buffer |
Not recommended. |
sign_key |
(Extra) You can specify signature key for HTTP event sink . When Flussonic prepares HTTP POST with JSON body, it will add this secret key to the end of the body, making SHA1 hash from it and adding it in hex form as a header X-Signature. This can be used for verifying that it is Flussonic posting events. |
All other configuration options in this block will be passed to the specified sink handler.
In a LUA script they can be accessed via the args
table.
When using HTTP backend you pass them along with other parameters.
Event filtering
You can pre-filter events before passing them to handlers. It is a very important mechanism, try to use it, because it reduces the load on your event handler. Each event is prefiltered in the emitter thread before being passed to the handler.
Rules for filtering:
- if any
except
directive fully matches event, it is dropped and not sent to handler; - if there are no
only
directives, events are sent to handler; - if there are
only
directive then event is passed to handler if ANY directive fully matches the event.
Full match of an event and a directive means that all key=value
pairs in directive are equal to values in event.
If a directive has a key=value1,value2,value3
pair, then it means that the event must have any of these values to match this directive.
Examples:
only event=stream_opened;
matches{event: "stream_opened", media: "cbc"}
only event=stream_opened,stream_closed;
matches{event: "stream_opened", media: "cbc"}
only event=stream_opened,stream_closed media=tnt;
does not match{event: "stream_opened", media: "cbc"}
only event=stream_opened media=cbc group=news;
does not match{event: "stream_opened", media: "cbc"}
The UI for event logging and filtering
In the UI, go to Config > Events and select event processing options:
If the option you need is missing among the boxes, you can set it in Extended.
The list of events
Here is a list of the most popular events. You can find the descriptions of other events in the API schema (see the events
parameter of the response).
Events | Description |
---|---|
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. |
Examples of configuring email notifications
Let's learn what you can do with events system. For example, let's receive email notifications if a stream is down.
The simplest configuration will be:
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;
}
This configuration is enough unless you want to filter streams here.
What no_video.lua
can do:
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})
You need to install the Sendmail utility to send mail correctly:
apt-get install sendmail
Make sure that Sendmail listens on the port specified in the configuration file:
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
Specify real domain name as the hostname of the server:
streamer1.my.cdn
Performance-related events
Flussonic event system allows setting up notifications on resource consumption and performance issues.
Such events as busy_port
, busy_dist_port
, long_gc
, long_schedule_pid
and long_schedule_port
are those of the Erlang’s system monitor. Refer to the Erlang documentation for the description, cases when each of them occurs, and what parameters they pass. These events can indicate performance problems.
In Flussonic, all these events belong to the system_overloaded
group. The group of events is specified within the group
keyword.
Sample configuration:
event_sink performance_handler {
url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
only group=system_overloaded;
}
In this example, the group=system_overloaded
filter passes only the performance problems events to the handler.
Memory usage
The memory_usage
event occurs when memory is used exceedingly. The event has the parameters total
and used
, in bytes. Flussonic sends this event when it uses more than half of all available memory. When the 80% threshold is exceeded, the event is fired with the system_overloaded
group.
Reliable delivery of event notifications
To prevent notications loss, you can set up Flussonic for postponed attempts to resend notifications. If the receiving HTTP server or script does not respond, Flussonic accumulates events in a special buffer and periodically retries sending them. When the receiving server responds, Flussonic will send all the accumulated notifications.
For this, specify two options in the configuration file:
event_sink watcher {
url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
resend_notifications_limit 10;
resend_notifications_timeout 10;
}
where:
resend_notifications_limit
— the number of the most recent events that will be stored in order to retry sending them. Cannot exceed 2000.resend_notifications_timeout
— the time interval, in seconds, over which Flussonic will try to send events again.
RTSP stream monitoring
Here is a group of events that signals a corrupted RTSP stream:
Events | Description |
---|---|
rtsp_desync |
audio and video streams are not synchronized |
rtsp_resync |
audio and video streams have been synchronized |
rtsp_broken_data |
Flussonic receives broken data from the camera |
Here is how it looks like in the configuration file:
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;
}
Advertisement logging
You can use the ad_injected
event to log information about injecting and playing advertisement in live streams. Each time advertisement is inserted into a played stream, Flussonic generates this event with such parameters as the first advertisement frame DTS, the path to the advertisement files, advertisement type and duration. For details please refer to the API schema (select ad_injected
in the events
parameter of the response).
This event is written to Flussonic log allowing to monitor, how much advertisement have Flussonic showed and to whom.