Alerting

mediarithmics modules can trigger alerts to grab the attention of users/integrators on specific points to improve or fix.

Alerts are displayed in the UI, but can also be accessed by API if you want to automate actions or grab them in your own reports.

Alert types

Here are the various alert types that exist:

Type	Trigger
SEGMENT_DEFINITION_ERROR	Error in the segment definition. More information here
SEGMENT_VOLUME_DROP	Segment volume drops by more than a configured threshold (in percentage). In the segment computation process, after it has been computed, we check If volumes have dropped by more than XX% If none of the segment labels are in the blocklist when in blocklist mode If any of the segment labels are in the allowlist when in allowlist mode More information here
INITIAL_LOADING_ERROR	Error during initial loading of a feed attached to a segment More information here
SEGMENT_COMPUTATION_ERROR	Error during the calculation of a segment More information here

Alert properties

Alerts have several properties associated:

• type: The type of the alert (e.g., SEGMENT_COMPUTATION_ERROR, SEGMENT_VOLUME_DROP...)

• id: The unique identifier of the alert

• datamart_id: The identifier of the datamart associated with the alert

• organisation_id: The identifier of the organisation associated with the alert

• community_id: The identifier of the community associated with the alert

• created_ts: The timestamp indicating when the alert was created

• archived: A flag indicating whether the alert is closed/archived (true) or open (false)

• archived_ts: The timestamp indicating when the alert was closed/archived

• archived_by: The identifier of the user that closed/archived the alert

• expiration: The expiration timestamp for the alert

• count: The number of times the alert has been triggered

• last_count_ts: The timestamp of the most recent trigger of the alert

Polymorphism

The alerting system supports polymorphism to accommodate specific fields for various alert types.

For Segment alert

Alert type	Property name	Value
-	segment	{ 'segment_id': 'xxx', 'segment_name': 'The segment name', 'segment_type': 'USER_QUERY', 'user_points_count': 71989, 'feeds_count': 0 }
SEGMENT_INITIAL_LOADING	alert_sub_type	sub-type of the error: INITIAL_LOADING_EXECUTION_ON_ERROR INITIAL_LOADING_RECORDS_ERROR INITIAL_LOADING_NOT_STARTING INITIAL_LOADING_RUNNING_TOO_LONG
SEGMENT_INITIAL_LOADING	feed_id	ID of the feed concerned by the error
SEGMENT_VOLUME_DROP	drop_rate	Total drop (in percentage) of the segment volume since the alert was first triggered

Open/Close

To provide a familiar terminology to users, alerts can be opened or closed. However, in the system, the open/closed state is represented by the archived field. Opening an alert sets the archived field to false, while closing an alert sets it to true. The closed state implies that the alert is no longer active or visible to users.

Preventing duplicates

To avoid having multiple instances of the same alert, the system employs a prevention mechanism. Each alert has count and count_last_ts properties. When triggering a new alert, we check if there is already an active alert for the same target. If such an alert exists, the system increments the count property and updates the count_last_ts to reflect the latest trigger. This prevents the proliferation of identical alerts and ensures that only one alert remains active with an incremented counter.

For example, if a segment has a query error and the issue persists without resolution, the system will increment the count property of the existing alert rather than creating multiple duplicate alerts.

The count_last_ts property stores the timestamp of the most recent trigger, while the created_ts property stores the timestamp of the initial trigger.

Expiration

To manage the storage of alerts and ensure their relevance, the system implements an expiration mechanism. Alerts have an expiration duration associated with them. It is set to the created_ts + 1 month. You can't modify this behavior.

A cleaning job runs regularly to identify and delete all expired alerts from the database. This prevents the accumulation of unnecessary historical data.

API

The API allows users and integrators to interact with alerts through the following functionalities:API

Retrieve a list of alerts based on specific criteria

GET https://api.mediarithmics.com/v1/alerts

Paginated API.

You have to fill in either the organisation_id, datamart_id or community_id parameters.

Archived alerts are not returned by default. You need to ask them through the archived parameter.

Query Parameters

Name	Type	Description
organisation_id	Int	ID of the organisation in which to find alerts
datamart_id	Int	ID of the datamart in which to find alerts
community_id	Int	ID of the community in which to find alerts
type	AlertType	Such as SEGMENT_COMPUTATION_ERROR. See Alert types.
archived	Boolean	true to return archived alerts.

401: Unauthorized You don't have access to the organisation, datamart or community

200: OK List of alerts

Change the status of an alert from open to closed or vice versa

PUT https://api.mediarithmics.com/v1/alerts/:alertId

Path Parameters

Name	Type	Description
alertId	Int	ID of the alert to edit

Query Parameters

Name	Type	Description
archive	boolean	true to close an alert, false to open it.

401: Unauthorized You can't open/close this alert

200: OK OK. Returns the new alert object.

400: Bad Request Missing parameter: archive

DELETE https://api.mediarithmics.com/v1/alerts/:alertId

Path Parameters

Name	Type	Description
alertId	Int	ID of the alert to delete

401: Unauthorized

200: OK

No other operations or modifications are permitted through the API.

Users and integrators are restricted from editing any field other than the archived flag for an alert.