A YANG Data Model for Alarm Management
Extracted elements (29)
Alarms are modeled as states on resources rather than as discrete notifications, so that 'link-down' and 'link-up' notifications are treated as two events updating the same 'link-alarm' state. This eliminates ambiguity in alarm/clear correlation present in X.733 and 3GPP Alarm IRP.
The recommended practice is to raise a single alarm on the root-cause resource and enumerate affected resources in the impacted-resource leaf-list, rather than generating separate alarms per affected resource. This limits alarm volume and directs operators to the actionable resource.
X.733 mapping concepts are kept in a separate companion module (ietf-alarms-x733) rather than the core model, in order to keep the core model small and easy to understand while still allowing systems that require X.733 compliance to support it.
YANG identities are used for alarm-type-id because they are hierarchical and distributed, enabling vendors and SDOs to define their own alarm type hierarchies without a central registry. A string qualifier is added for alarm types not fully known at design time (e.g., user-configurable digital inputs).
A companion module (ietf-alarms-x733, Section 7) provides explicit field mappings to ITU-T X.733, including event-type, probable-cause, specific-problem, backed-up-status, backup-object, trend-indication, threshold-information, and correlated-notifications.
The ietf-alarms model maps to RFC 8348 (ietf-hardware): al:resource corresponds to hardware component list entries, al:is-cleared maps to no bits set in hw:alarm-state, al:perceived-severity maps to corresponding severity bits, and al:operator-state 'ack' maps to hw:under-repair.
A server MUST implement the alarm inventory, and the mechanism whereby dynamic alarm types are added using the alarm-type qualifier MUST populate this list, enabling controlled alarm procedures in the client.
A server SHOULD describe its alarm retention policy: how long it retains cleared/closed alarms before they are manually purged or auto-removed.
If an alarm matches a configured alarm-severity-assignment-profile, it MUST use the configured severity level(s) instead of the system default, and this override MUST also be reflected in the alarm inventory.
If the alarming resource exists in the YANG data tree, an instance-identifier MUST be used with the full path to the object to identify the resource.
Implementations SHOULD strive to detect the cleared state for all alarm types; the alarm-inventory will-clear leaf MUST be set to false only when no cleared state is logically possible or instrumentation is missing.
Shelved alarms MUST appear in the /alarms/shelved-alarms/shelved-alarm list; non-matching alarms MUST appear in /alarms/alarm-list/alarm. The server MUST maintain state changes (e.g., severity) for shelved alarms and MUST NOT send notifications for them.
The alarm-list and alarm-inventory MUST be implemented by any system supporting this module. All other data model features (operator-actions, alarm-shelving, alarm-history, alarm-summary, alarm-profile, severity-assignment) are conditional YANG features.
The alarm-text leaf MUST contain enough information for an operator to understand the problem and how to resolve it. If the string contains structure, that format should be clearly documented.
The base alarm-type-id identity is abstract and MUST NOT be used for alarms or appear in the alarm inventory; it serves only as a base for derived concrete alarm-type identities.
The entry with the latest timestamp in the status-change list MUST correspond to the 'is-cleared', 'perceived-severity', and 'alarm-text' leaves of the alarm. The /alarm-list/alarm/last-changed MUST be set to the same value as the time of the state change.
An alarm instance is uniquely identified by the three-leaf key (resource, alarm-type-id, alarm-type-qualifier). All notifications sharing these three values are considered updates to the same alarm instance, removing ambiguity in alarm/clear correlation.
Each alarm may optionally carry root-cause-resource (leaf-list, feature root-cause-analysis), impacted-resource (leaf-list, feature service-impact-analysis), and related-alarm (list, feature alarm-correlation) to support analysis without mandating it.
Operator state is a union of writable states (none, ack, closed) and server-assigned states (shelved, un-shelved). Operators close alarms but cannot clear them; only the underlying instrumentation can clear an alarm via is-cleared.
The alarm inventory (/alarms/alarm-inventory) lists all possible concrete alarm types with fields: alarm-type-id, alarm-type-qualifier, resource (optional), will-clear (boolean, mandatory), severity-level (leaf-list), and description (mandatory).
The notify-status-changes control leaf governs notification generation: all-state-changes (default), raise-and-clear only, or severity-level (changes crossing a configured severity threshold, with clears always sent). This implements ITU-T Alarm Report Control.
The purge-alarms action deletes alarms from the alarm list matching a filter on clearance status, age (seconds/minutes/hours/days/weeks), severity (below/is/above), and operator state. The compress-alarms action removes all status-change history entries except the most recent.
The resource typedef is a union of instance-identifier (for YANG-modeled objects), yang:object-identifier (for SNMP objects), string (for distinguished names, CIM paths, etc.), and yang:uuid. Server precedence follows the union order.
The severity typedef enumerates five ordered levels: indeterminate (2), warning (3), minor (4), major (5), and critical (6), drawn from ITU-T X.733. Clearance is a separate boolean 'is-cleared' flag; 'cleared' is not a severity value.
This document registers two YANG modules in the IANA 'YANG Module Names' registry: 'ietf-alarms' with namespace 'urn:ietf:params:xml:ns:yang:ietf-alarms', and 'ietf-alarms-x733' with namespace 'urn:ietf:params:xml:ns:yang:ietf-alarms-x733'.
The ietf-alarms module contains writable nodes (alarm shelving, alarm profiles, control parameters, set-operator-state) that could be misused to suppress or reclassify alarms, hiding network faults. Implementations must enforce access control per RFC 8341 (NACM) or equivalent.
The purge-alarms and compress-alarms actions are destructive and irreversible, permanently deleting alarm history that may be needed for fault analysis or audit. Access to these operations must be restricted to authorized administrative roles.
Operator alarm lifecycle: none → ack → closed (operator-set via set-operator-state action); shelved/un-shelved are server-assigned on shelf configuration changes. Purge-alarms removes the alarm entry from the list entirely (administrative transition).
Resource alarm lifecycle: raised (is-cleared=false, with perceived-severity) → severity-changed (same key, new severity/text) → cleared (is-cleared=true) → re-raised. Only instrumentation drives transitions; each change appends an entry to the status-change list if alarm-history is supported.