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. You can find the list and descriptions of all the events in the API schema.

It would also be useful for you to read more about streaming sessions.

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

To configure event-related settings, go to Config -> Events or add the event_sink directive into the Flussonic configuration file.

In the Sink (or url in the config file) option, 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
• 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. This feature can be configured at Config -> Events.

The same settings can be performed in the config file by adding the event_sink directive and specifying the file in url log:// option, for example:

event_sink log_name {
    url log:///var/log/flussonic/crash.log;
    level debug;
}

The main settings are:

• Name (log_name) is just the setting's name. It's good to give it a meaningful name.
• Sink (url) is the file where event information is logged. See also Configuring event handlers.
• Level (level) is the level of logging according to event importance. Can be debug (the most detailed logging), info, alert (only serious events), notice, warning, error, critical.

Configuring event handlers¶

Flussonic can send events to any recipient you specify in the Sink (url) parameter. This may be the path to the script file, the URL of the remote handler, and so on. For example:

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. Try using filtering to reduce the event traffic.

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:

All other configuration options in this block will be passed to the specified sink handler. See the full list of options in the description of the API call: Flussonic-API: PUT /streamer/api/v3/event_sinks/{name}/. 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 or files with Except (except) and Only (only) options. This mechanism 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"}

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=*;
    level debug;
}

Example of configuration to send only certain events to the handler:

event_sink handler_name {
    url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
    only event=stream_opened,stream_closed,source_opened,source_closed;
}

Reliable delivery of event notifications¶

To prevent notifications 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:

• Resend limit resend_limit is the number of the most recent events that will be stored in order to retry sending them. Cannot exceed 2000.
• Resend timeout resend_timeout is the time interval, in seconds, over which Flussonic will try to send events again.

In the config file, it will look like this:

event_sink watcher {
   url http://IP-ADDRESS:PORT/SCRIPT_NAME.php;
   resend_limit 10;
   resend_timeout 10;
}

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.