Alarmist (alarmist v0.2.2)

View Source

Alarm handler and more

Alarmist provides an :alarm_handler implementation that allows you to check what alarms are currently active and subscribe to alarm status changes.

It also provides a DSL for defining alarms based on other alarms. See Alarmist.Definition.

Summary

Types

Alarm information

Alarm description

Alarm identifier

Alarm state

Functions

Add a rule-based alarm

Manually add a rule-based alarm

Return a list of all active alarm IDs

Return a list of all active alarms

Remove a rule-based alarm

Subscribe to alarm status events

Subscribe to alarm status events for all alarms

Return all synthetic alarm IDs

Unsubscribe the current process from the specified alarm :set and :clear events

Unsubscribe from alarm status events for all alarms

Types

alarm()

@type alarm() :: {alarm_id(), alarm_description()}

Alarm information

Calls to :alarm_handler.set_alarm/1 pass an alarm identifier and description as a 2-tuple. Alarmist stores the description of the most recent call.

:alarm_handler.set_alarm/1 doesn't enforce the use of 2-tuples. Alarmist normalizes non-2-tuple alarms so that they have empty descriptions.

alarm_description()

@type alarm_description() :: any()

Alarm description

This is optional supplemental information about the alarm. It could contain more information about why it was set. Don't use it to differentiate between alarms. Use the alarm ID for that.

alarm_id()

@type alarm_id() :: atom()

Alarm identifier

Alarm identifiers are the unique identifiers of each alarm that can be set or cleared.

While SASL alarm identifiers can be anything, Alarmist imposes the restriction that they all be atoms. It is highly recommended to use module names to avoid naming collisions. Non-atom alarms are currently ignored by Alarmist.

alarm_state()

@type alarm_state() :: :set | :clear

Alarm state

Alarms are in the :set state after a call to :alarm_handler.set_alarm/1 and in the :clear state after a call to :alarm_handler.clear_alarm/1. Redundant calls to :alarm_handler.set_alarm/1 update the alarm description and redundant calls to :alarm_handler.clear_alarm/1 are ignored.

compiled_rules()

@type compiled_rules() :: [Alarmist.Compiler.rule()]

Functions

add_synthetic_alarm(alarm_id)

@spec add_synthetic_alarm(module()) :: :ok

Add a rule-based alarm

After this call, Alarmist will watch for alarms to be set based on the supplied rules and set or clear the specified alarm ID. The alarm ID needs to be unique.

Calling this function a multiple times with the same alarm results in the previous alarm being replaced. Alarm subscribers won't receive redundant events if the rules are the same.

add_synthetic_alarm(alarm_id, compiled_rules)

@spec add_synthetic_alarm(alarm_id(), compiled_rules()) :: :ok

Manually add a rule-based alarm

Use this when not using defalarm.

After this call, Alarmist will watch for alarms to be set based on the supplied rules and set or clear the specified alarm ID. The alarm ID needs to be unique.

get_alarm_ids()

@spec get_alarm_ids() :: [alarm_id()]

Return a list of all active alarm IDs

get_alarms()

@spec get_alarms() :: [alarm()]

Return a list of all active alarms

This returns {id, description} tuples. Note that Alarmist normalizes alarms that were not set as 2-tuples so this may not match calls to :alarm_handler.set_alarm/1 exactly.

remove_synthetic_alarm(alarm_id)

@spec remove_synthetic_alarm(alarm_id()) :: :ok

Remove a rule-based alarm

subscribe(alarm_id)

@spec subscribe(alarm_id()) :: :ok

Subscribe to alarm status events

Events will be delivered to the calling process as:

%Alarmist.Event{
  id: TheAlarmId,
  state: :set,
  description: nil,
  timestamp: -576460712978320952,
  previous_state: :unknown,
  previous_timestamp: -576460751417398083
}

subscribe_all()

@spec subscribe_all() :: :ok

Subscribe to alarm status events for all alarms

See subscribe/1 for the event format.

synthetic_alarm_ids()

@spec synthetic_alarm_ids() :: [alarm_id()]

Return all synthetic alarm IDs

unsubscribe(alarm_id)

@spec unsubscribe(alarm_id()) :: :ok

Unsubscribe the current process from the specified alarm :set and :clear events

unsubscribe_all()

@spec unsubscribe_all() :: :ok

Unsubscribe from alarm status events for all alarms

NOTE: This will only remove subscriptions created via subscribe_all/0, not subscriptions created for individual alarms via subscribe/1.