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 directory that is
  18 searched by default, usually something like /usr/local/lib.
  19
  20 The alarm feature opens a direct connection to the alarm manager
  21 using the RMR library's wormhole feature, taking the host name and
  22 port number from environment variables defined as the constants
  23 `ALARM_MGR_SERVICE_NAME_ENV` and `ALARM_MGR_SERVICE_PORT_ENV` in
  24 the `ricxappframe.alarm.alarm` module. The message type is set to
  25 constant `RIC_ALARM_UPDATE` in the `ricxappframe.alarm.alarm` module,
  26 currently 13111.
  27
  28 The complete API for the Alarm feature appears below.
  29
  30
  31 Example Usage
  32 -------------
  33
  34 Alarms are created, raised and cleared using an `AlarmManager` as
  35 shown below. The manager requires an RMR context at creation time.
  36
  37 .. code-block:: python
  38
  39     from ricxappframe.alarm import alarm
  40     from ricxappframe.rmr import rmr
  41
  42     rmr_context = rmr.rmr_init(b"4562", rmr.RMR_MAX_RCV_BYTES, 0x00)
  43     alarm_mgr = alarm.AlarmManager(rmr_context, "managed-object-id", "application-id")
  44     alarm3 = alarm_mgr.create_alarm(3, alarm.AlarmSeverity.DEFAULT, "identifying", "additional")
  45     success = alarm_mgr.raise_alarm(alarm3)
  46
  47
  48
  49 Alarm API
  50 ---------
  51
  52 .. automodule:: ricxappframe.alarm.alarm
  53     :members:
  54
  55
  56 Alarm Messages
  57 --------------
  58
  59 Alarm messages conform to the following JSON schema.
  60
  61 .. literalinclude:: ../ricxappframe/alarm/alarm-schema.json
  62   :language: JSON