docs/alarm_api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2020 AT&T Intellectual Property
   4
   5 RIC Alarm API
   6 =============
   7
   8 Overview
   9 --------
  10
  11 The xapp python framework provides an alarm feature in the python
  12 subpackage `ricxappframe.alarm`.  This subpackage defines objects and
  13 methods for creating, raising and clearing alarms.
  14
  15 The alarm feature reuses the `ricxappframe.rmr` subpackage for
  16 transporting alarm messages. That in turn requires the RMR
  17 shared-object library to be available in a system library that is
  18 searched by default, usually something like /usr/local/lib.
  19
  20 The alarm feature sends messages using RMR message type
  21 `RIC_ALARM_UPDATE` in the `ricxappframe.alarm.alarm` module, currently
  22 value 13111. The Xapp's routing table must have one (or more) entries
  23 for that message type.
  24
  25 The complete API for the Alarm feature appears below.
  26
  27
  28 Example Usage
  29 -------------
  30
  31 Alarms are created, raised and cleared using an `AlarmManager` as
  32 shown below. The manager requires an RMR context at creation time.
  33
  34 .. code-block:: python
  35
  36     from ricxappframe.alarm import alarm
  37     from ricxappframe.rmr import rmr
  38
  39     rmr_context = rmr.rmr_init(b"4562", rmr.RMR_MAX_RCV_BYTES, 0x00)
  40     alarm_mgr = alarm.AlarmManager(rmr_context, "managed-object-id", "application-id")
  41     alarm3 = alarm_mgr.create_alarm(3, alarm.AlarmSeverity.DEFAULT, "identifying", "additional")
  42     success = alarm_mgr.raise_alarm(alarm3)
  43
  44
  45
  46 Alarm API
  47 ---------
  48
  49 .. automodule:: ricxappframe.alarm.alarm
  50     :members:
  51
  52
  53 Alarm Messages
  54 --------------
  55
  56 Alarm messages conform to the following JSON schema.
  57
  58 .. literalinclude:: ../ricxappframe/alarm/alarm-schema.json
  59   :language: JSON