Alarm

class lsst.ts.watcher.Alarm(name)

Bases: object

A Watcher alarm.

Parameters:
name : str

Name of alarm. This must be unique among all alarms and should be of the form system.[subsystem….]_name so that groups of related alarms can be acknowledged.

Attributes Summary

muted Is this alarm muted?
nominal True if alarm is in nominal state: severity = max severity = NONE.

Methods Summary

acknowledge(severity, user) Acknowledge the alarm.
assert_equal(other[, ignore_attrs]) Assert that this alarm equals another alarm.
close() Cancel pending tasks.
configure([callback, …]) Configure the callback function and auto ack/unack delays.
mute(duration, severity, user) Mute this alarm for a specified duration and severity.
reset() Reset the alarm to nominal state.
set_severity(severity, reason) Set the severity.
unacknowledge([escalate]) Unacknowledge the alarm.
unmute() Unmute this alarm.

Attributes Documentation

muted

Is this alarm muted?

nominal

True if alarm is in nominal state: severity = max severity = NONE.

When the alarm is in nominal state it should not be displayed in the Watcher GUI.

Methods Documentation

acknowledge(severity, user)

Acknowledge the alarm.

Almost a no-op if nominal or acknowledged. If acknowledged restart the auto-unack timer, if wanted.

Parameters:
severity : lsst.ts.idl.enums.Watcher.AlarmSeverity or int

Severity to acknowledge. Must be >= self.max_severity. If the severity goes above this level the alarm will unacknowledge itself.

user : str

Name of user; used to set acknowledged_by.

Returns:
updated : bool

True if the alarm state changed (any fields were modified other than tasks being cancelled), False otherwise.

Raises:
ValueError

If severity < self.max_severity and the alarm was not already acknowledged.

Notes

The reason severity is an argument is to handle the case that a user acknowledges an alarm just as the alarm severity increases. To avoid the danger of accidentally acknowledging at a higher severity than intended, the command must be rejected.

assert_equal(other, ignore_attrs=())

Assert that this alarm equals another alarm.

Compares all attributes except tasks and those specified in ignore_attrs.

Parameters:
other : Alarm

Alarm to compare.

ignore_attrs : list [str], optional

Sequence of attribute names to ignore (in addition to task attributes, which are always ignored.)

close()

Cancel pending tasks.

configure(callback=None, auto_acknowledge_delay=0, auto_unacknowledge_delay=0, escalate_to='', escalate_delay=0)

Configure the callback function and auto ack/unack delays.

Parameters:
callback : callable, optional

Function or coroutine to call whenever the alarm changes state, or None if no callback wanted. The function receives one argument: this alarm.

auto_acknowledge_delay : float, optional

Delay (in seconds) before a stale alarm is automatically acknowledged, or 0 for no automatic acknowledgement. A stale alarm is one that has not yet been acknowledged, but its severity has gone to NONE.

auto_unacknowledge_delay : float, optional

Delay (in seconds) before an acknowledged alarm is automatically unacknowledged, or 0 for no automatic unacknowledgement. Automatic unacknowledgement only occurs if the alarm persists, because an acknowledged alarm is reset if severity goes to NONE.

escalate_to : str, optional

Who or what to escalate the alarm to. If “” (the default) the alarm is not escalated.

escalate_delay : float, optional

Delay before escalating a critical unacknowledged alarm (sec). If 0 (the default) the alarm is not escalated.

mute(duration, severity, user)

Mute this alarm for a specified duration and severity.

Parameters:
duration : float

How long to mute the alarm (sec).

severity : lsst.ts.idl.enums.Watcher.AlarmSeverity or int

Severity to mute. If the alarm’s current or max severity goes above this level the alarm should be displayed.

user : str

Name of user who muted this alarm. Used to set muted_by.

Raises:
ValueError

If duration <= 0, severity == AlarmSeverity.NONE or severity is not a valid AlarmSeverity enum value.

Notes

An alarm cannot have multiple mute levels and durations. If mute is called multiple times, the most recent call overwrites information from earlier calls.

reset()

Reset the alarm to nominal state.

Do not call the callback function.

This is designed to be called when enabling the model. It sets too many fields to be called by set_severity.

set_severity(severity, reason)

Set the severity.

Parameters:
severity : lsst.ts.idl.enums.Watcher.AlarmSeverity or int

New severity.

reason : str

The reason for this state; this should be a brief message explaining what is wrong. Ignored if severity is NONE.

Returns:
updated : bool

True if the alarm state changed (i.e. if any fields were modified), False otherwise.

unacknowledge(escalate=True)

Unacknowledge the alarm. Basically a no-op if nominal or not acknowledged.

Returns:
updated : bool

True if the alarm state changed (i.e. if any fields were modified), False otherwise.

escalate : bool, optional

Restart the escalation timer? Only relevant if max_severity is CRITICAL.

unmute()

Unmute this alarm.