Events API

Events in Flussonic

Flussonic has a system of internal events with routing and handling, and convenient and flexible tools to configure it.

Events are initiated in different parts of the system and can be used in different scenarios.

To configure event-related settings, add into the Flussonic configuration file a directive notify and the option sink where you define the receiver of events:

• To use your custom handler, specify the path to the handler in sink.
• To write event to a log file, specify the path to the file in sink.

Then use various options to filter events before they come to a handler or log.

On this page:

• 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 notify directive and use the sink log:// option to specify the file, for example:

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

Where:

• log_name — just the setting's name. It's good to give it a meaningful name.
• sink — the file where event information is logged.
• verbose — the level of logging according to event importance. Can be debug (the most detailed logging), info, or alert (only serious events).

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):

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

Configuring event handlers

Each event handler can be declared in config:

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

Such configuration creates an event handler with the name handler_name and it sends ALL events to HTTP URL http://backend.local/notify.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:

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

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:

sink

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.

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.

Here goes some extra configuration options:

sign_key

You can specify signature key for HTTP event sink. When Flussonic will prepare HTTP POST with JSON body, it will add this secret key to then end of body, make SHA1 hash from it and add it in hex form as a header X-Signature. This can be used for verifying that it is a Flussonic posting events.

Event filtering

You can pre-filter events before passing them to handlers. It is very important mechanism, try to use it, because it reduce 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_started; matches {event: "stream_started", media: "cbc"}
• only event=stream_started,stream_stopped; matches {event: "stream_started", media: "cbc"}
• only event=stream_started,stream_stopped media=tnt; NOT matches {event: "stream_started", media: "cbc"}
• only event=stream_started media=cbc group=news; NOT matches {event: "stream_started", 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 known events:

server_started	The server has started
listener_start	Flussonic starts listening on some port
listener_failure	Flussonic failed to listen on a port
config_reloaded	The configuration was reloaded
session_opened	A session was opened
session_closed	A session was closed
file_opened	A file was opened
file_closed	A file was closed
stream_started	A stream has started
stream_stop	A stream has received the command to stop via API
stream_stopped	A stream was stopped
stream_reconfigured	A stream configuration was updated
stream_motion_started	(Applies to IP cameras) Detected motion has started
stream_motion_stopped	(Applies to IP cameras) Detected motion has stopped
source_ready	A stream has received first video frames
stream_media_info	Stream attributes (media_info) were changed
source_lost	The stream source is considered to be lost and the stream needs restarting
source_switch	A stream has switched to another source
frames_timed_out	A stream's source has stopped sending frames (but it is not restarted yet)
frames_restored	A stream's source has resumed sending frames
stream_backup	A backup file has started playing while the source is lost
publish_started	Publishing to a stream has started
publish_stopped	Publishing to a stream has finished (you can get a lot of valuable information with this event)
push_started	A stream has started sending video (push) to another source
stream_jpeg	A new JPEG thumbnail has been generated
dvr_new_fragment	The next fragment of the DVR archive was recorded on disk
dvr_deleted_fragments	Old fragments were purged from the DVR archive
dvr_new_blob	A new one-hour interval was opened for recording video to DVR
stream_force_close_gop	Stream error: invalid timestamps are coming or too low FPS
stream_rt_sync	A stream had to resync timestamps. This might be the indication of stream errors if happens too often.
stream_broken_source	Flussonic failed to read a stream from the source and restarted the stream
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 was completed
dvr_replication_progress	DVR replication is in progress
dvr_replication_done	DVR replication was completed
udp_pusher_does_not_fit_cbr	A stream that you send via [UDP with constant bitrate](../video-playback/udp-multicast-with-constant-bitrate.md#play-cbr-udp-page) (using the configuration push udp://IP_ADDRESS?cbr=...) has a too high bitrate that can cause buffer overflow. As a result, a stream error or stream restart can occur. To avoid this, you can transcode the stream into smaller bitrate.

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:

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;
}

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:

hostname
streamer1.my.cdn

Performance-related events

The Flussonic’s event system allows setting up notifications on resource consumption and performance issues.

The events 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 their 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 with the group keyword.

Sample configuration:

notify performance_handler {
    sink http://backend.local/notify.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:

notify watcher {
   sink http://backend.local/notify.php;
   resend_notifications_limit 1000;
   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.