Alarmist (alarmist v0.3.1)

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.Alarm.

Summary

Types

alarm()

Alarm information

alarm_description()

Alarm description

alarm_id()

Alarm identifier

alarm_pattern()

Patterns for alarm subscriptions

alarm_state()

Alarm state

alarm_type()

Alarm type

compiled_condition()
info_options()

See Alarmist.info/1

rule()

Functions

add_managed_alarm(alarm_id)

Add a managed alarm

alarm_type(alarm_id)

Extract the alarm type from an alarm ID

clear_alarm_level(alarm_id)

Clear knowledge of an alarm's level

get_alarm_ids(options \\ [])

Return a list of all active alarm IDs

get_alarms(options \\ [])

Return a list of all active alarms

info(options \\ [])

Print alarm status in a nice table

is_alarm_id(id)
managed_alarm_ids()

Return all managed alarm IDs

remove_managed_alarm(alarm_id)

Remove a managed alarm

set_alarm_level(alarm_id, level)

Set or change the alarm level for an alarm

subscribe(alarm_pattern)

Subscribe to alarm status events

subscribe_all()

Subscribe to alarm status events for all alarms

unsubscribe(alarm_pattern)

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

unsubscribe_all()

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() ::
  alarm_type()
  | {alarm_type(), any()}
  | {alarm_type(), any(), any()}
  | {alarm_type(), any(), any(), any()}

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 supplies conventions so that it can interpret them. This typespec follows those conventions, but you may come across codes that doesn't. Those cases may be ignored or misinterpreted.

alarm_pattern()

@type alarm_pattern() ::
  alarm_type()
  | :_
  | {alarm_type() | :_, any() | :_}
  | {alarm_type() | :_, any() | :_, any() | :_}

Patterns for alarm subscriptions

Patterns can be exact matches or use :_ to match any value in a position.

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.

alarm_type()

@type alarm_type() :: atom()

Alarm type

Alarm types are atoms and for Alarmist-managed alarms, they are module names.

compiled_condition()

@type compiled_condition() :: %{
  rules: [rule()],
  temporaries: [alarm_id()],
  options: map()
}

info_options()

@type info_options() :: [
  level: Logger.level(),
  sort: :level | :alarm_id | :duration,
  ansi_enabled?: boolean()
]

See Alarmist.info/1

rule()

@opaque rule()

Functions

add_managed_alarm(alarm_id)

@spec add_managed_alarm(alarm_id()) :: :ok

Add a managed alarm

After this call, Alarmist will watch for alarms to be set based on the supplied module and set or clear the specified alarm ID. The module must use Alarmist.Alarm.

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.

alarm_type(alarm_id)

@spec alarm_type(alarm_id()) :: alarm_type()

Extract the alarm type from an alarm ID

Examples:

iex> Alarmist.alarm_type(MyAlarm)
MyAlarm
iex> Alarmist.alarm_type({NetworkBroken, "eth0"})
NetworkBroken

clear_alarm_level(alarm_id)

@spec clear_alarm_level(alarm_id()) :: :ok

Clear knowledge of an alarm's level

If the alarm gets reported after this call, it will be assigned the default alarm level, :warning.

get_alarm_ids(options \\ [])

@spec get_alarm_ids([{:level, Logger.level()}]) :: [alarm_id()]

Return a list of all active alarm IDs

Options:

  • :level - filter alarms by severity. Defaults to :info.

get_alarms(options \\ [])

@spec get_alarms([{:level, Logger.level()}]) :: [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.

Options:

  • :level - filter alarms by severity. Defaults to :info.

info(options \\ [])

@spec info(info_options()) :: :ok

Print alarm status in a nice table

Options:

  • :level - filter alarms by severity. Defaults to :info.
  • :sort - :level, :alarm_id, or :duration. Defaults to :level.
  • :ansi_enabled? - override the default ANSI setting. Defaults to true.

is_alarm_id(id)

(macro)

managed_alarm_ids()

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

Return all managed alarm IDs

remove_managed_alarm(alarm_id)

@spec remove_managed_alarm(alarm_id()) :: :ok

Remove a managed alarm

set_alarm_level(alarm_id, level)

@spec set_alarm_level(alarm_id(), Logger.level()) :: :ok

Set or change the alarm level for an alarm

The alarm can be either for a managed or unmanaged alarm. Once set, that alarm will be reported with the specified level.

While this can be used with managed alarms, you should normally pass the desired level as an option to use Alarmist.Alarm so that it's handled for you.

It's also possible to set levels for unmanaged alarms in the application configuration:

config :alarmist, alarm_levels: %{MyUnmanagedAlarm => :critical}

NOTE: Changing the alarm level does not change the status of existing alarms since there's no mechanism to go back in time and change reports. Future events will be reported with the new level.

subscribe(alarm_pattern)

@spec subscribe(alarm_pattern()) :: :ok

Subscribe to alarm status events

Events will be delivered to the calling process as:

%Alarmist.Event{
  id: TheAlarmId,
  state: :set,
  description: nil,
  level: :warning,
  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.

unsubscribe(alarm_pattern)

@spec unsubscribe(alarm_pattern()) :: :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.