Alert Service¶

Introduction¶

The Alert Service use the following concepts:

Alert: Describes a notable and distinct condition of which the status can either be set active or inactive.
Alert Source: Represents a source for an Alert. It provides the means for changing the Alert Status.
Alert Status: This is simply the status of an alert, which can be active/set or inactive/unset.
Reduced Alert Status: The Reduced Alert Status represents the reduced or combined status of one or more Alert Statuses. If any one Alert is active in a set of alerts then the Reduced Alert Status is also active.

The Alert Service is a Component Framework facility that allows a component to communicate zero or more Alerts and an overall Reduced Alert Status. This facility is independent of the state machine and is meant to be used for important or otherwise notable, possibly actionable, events that does not meet the criteria for transitioning to an error state. An active alert condition may however be a pre-cursor to a more severe condition that cause component to transition to an error state.

Example alerts:

Buffer reached a configured high-water mark.

Reaching a high-water mark is not an error but may indicate that buffer exhaustion almost occurred and can be addressed by e.g. increasing buffer size.
Communicate non-fatal errors for improved diagnostics.

Data driven processing loops may encounter possibly transient errors that is not treated as fatal (no transition to error state). These are nevertheless important information that can help more quickly diagnose the system and where problems originate. An example of this is the Telemetry Subscriber which use latched alerts if a problem occurs when receiving DDS samples, sample processing or when writing to shared memory.

Observability¶

The RTC components make alerts available for observing in the following ways:

To observe alerts in the local component instance the rtctk::componentFramework::AlertServiceIf from the service container can be used (see more below). This provides direct access to the alert status.
Alerts are also published for RTC components automatically using the Event Service with the topic/event type AlertStatusEvent, which makes alerts accessible throughout the SRTC.
Finally the alert status changes are also logged using the logging system.

Usage¶

rtctk::componentFramework::AlertServiceIf is a accessible in the component framework service container and allows registration of alert conditions that can then be made active or inactive via the corresponding rtctk::componentFramework::AlertSource object.

First get access to the service instance from the component framework service container:

using rtctk::componentFramework::AlertServiceIf;

AlertServiceIf& alerts = m_services.Get<AlertServiceIf>();

Then the AlertSource can be created for a unique AlertDescription after which the alert can be made active or inactive.

Important

Modifying alert state (e.g. AlertSource::Set()) should be avoided from high priority or latency sensitive threads as the status change is signalled synchronously to the AlertServiceIf.
The AlertSource should be kept alive at least for as long as the alert is relevant. This normally implies that the alert should be stored in the business logic class.
When AlertSource is destroyed it will automatically reset any active alert (this may change in the future).

using rtctk::componentFramework::AlertDescription;
using rtctk::componentFramework::AlertSource;

// Create AlertSource for a specific alert, each of which must have a unique id in this
// component instance.
AlertSource buffer_alert = alerts.MakeAlertSource(AlertDescription(
    "buffer_hwm",  // unique id
    "Alert is latched active if buffer reach the configured high-water mark. "
    "Buffer size increase should be considered. "
    "Alert is reset when transitioning from Idle <-> Run. "));


// The condition can then be set or reset using the AlertSource:

// Changing alert status will notify the `AlertServiceIf` of the change via signal which in turn
// will emit the reduced signal together with all active alerts.
buffer_alert.Set();

// Resets alert.
buffer_alert.Reset();