Alarm

class lsst.ts.watcher.Alarm(name)

Bases: object

A Watcher alarm.

Parameters
namestr

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
namestr

Name of alarm.

auto_acknowledge_delayfloat

The delay (seconds) after which an alarm will be automatically acknowledged. Never if 0 (the default).

auto_unacknowledge_delayfloat

The delay (seconds) after which an alarm will be automatically unacknowleddged. Never if 0 (the default).

escalate_tostr

Who to escalate this alarm to. Do not escalate if blank (the default).

escalate_delayfloat

If an alarm goes to critical state and remains unacknowledged for this period of time (seconds), the alarm should be escalated. Do not escalate if 0 (the default).

severity_queueasyncio.Queue or None

Intended only for unit tests. Defaults to None. If a unit test sets this to an asyncio.Queue then __call__ will queue a severity every time it runs successfully.

Attributes Summary

callback

Get the callback function.

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.

assert_next_severity(expected_severity[, ...])

Wait for and check the next severity.

close()

Cancel pending tasks.

configure([callback, ...])

Configure the callback function and auto ack/unack delays.

init_severity_queue()

Initialize the severity queue.

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

callback

Get the callback function.

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

async acknowledge(severity, user)

Acknowledge the alarm.

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

Parameters
severitylsst.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.

userstr

Name of user; used to set acknowledged_by.

Returns
updatedbool

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
otherAlarm

Alarm to compare.

ignore_attrslist [str], optional

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

async assert_next_severity(expected_severity, check_empty=True, flush=False, timeout=10)

Wait for and check the next severity.

Only intended for tests. In order to call this you must first call init_severity_queue (once) to set up a severity queue.

Parameters
expected_severityAlarmSeverity

The expected severity.

check_emptybool, optional

If true (the default): check that the severity queue is empty, after getting the severity.

flushbool, optional

If true (not the default): flush all existing values from the queue, then wait for the next severity. This is useful for polling alarms.

timeoutfloat, optional

Maximum time to wait (seconds)

Raises
AssertionError

If the severity is not as expected, or if check_empty true and there are additional queued severities.

asyncio.TimeoutError

If no new severity is seen in time.

RuntimeError

If you never called init_severity_queue.

Notes

Here is the typical way to use this method: * Create a rule * Call rule.alarm.init_severity_queue() * Write SAL messages that are expected to change the alarm severity. * After writing each such message, call:

await rule.alarm.assert_next_severity(expected_severity)
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
callbackcallable, 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_delayfloat, 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_delayfloat, 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_tostr, optional

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

escalate_delayfloat, optional

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

init_severity_queue()

Initialize the severity queue.

You must call this once before calling assert_next_severity. You may call it again to reset the queue, but that is uncommon.

Warning

Only tests should call this method. Calling this in production code will cause a memory leak.

async mute(duration, severity, user)

Mute this alarm for a specified duration and severity.

Parameters
durationfloat

How long to mute the alarm (sec).

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

userstr

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.

async set_severity(severity, reason)

Set the severity.

Call the callback function unless the alarm was nominal and remains nominal. Put the new severity on the severity queue (if it exists), regardless of whether the alarm was nominal.

Parameters
severitylsst.ts.idl.enums.Watcher.AlarmSeverity or int

New severity.

reasonstr

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

Returns
updatedbool

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

async unacknowledge(escalate=True)

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

Returns
updatedbool

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

escalatebool, optional

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

async unmute()

Unmute this alarm.