README.md

   1 RIC Alarm Manager and Library Interface
   2 =======================================
   3
   4
   5 This repository containts Golang implementation of Alarm Manager and related application library interface.
   6
   7 Architecture
   8 ------------
   9
  10 ![Architecture](assets/alarm-adapter.png)
  11
  12 The **Alarm Library** provides a simple interface for RIC applications (both platform application and xApps) to raise, clear and re-raise. The **Alarm Library** interacts with the **Alarm Manager** via RMR interface.
  13
  14 The **Alarm Manager** is responsible for managing alarm situations in RIC cluster and interfacing with **Northboubd** applications such as **Prometheus AlertManager** to post the alarms as alerts. AlertManager takes care of deduplicating, silencing and inhibition (suppressing) of alerts, and routing them to the VESAgent, which, in turn, takes care of converting alerts to fault and send to ONAP as VES events.
  15
  16 Overview for Alarm Manager
  17 --------------------------
  18
  19 ### TBD
  20
  21 Overview for Alarm Library
  22 --------------------------
  23
  24 ## Initialization
  25
  26 A new alarm instance is created with InitAlarm function. MO and application identities are given as a parameter.
  27
  28 ## Alarm Context and Format
  29
  30 The Alarm object contains following parameters:
  31  * *SpecificProblem*: problem that is the cause of the alarm
  32  * *PerceivedSeverity*: The severity of the alarm, see above for possible values
  33  * *ManagedObjectId*: The name of the managed object that is the cause of the fault
  34  * *ApplicationId*: The name of the process raised the alarm
  35  * *AdditionalInfo*: Additional information given by the application
  36  * *IdentifyingInfo*: Identifying additional information, which is part of alarm identity
  37
  38  *ManagedObjectId* (mo), *SpecificProblem* (sp), *ApplicationId* (ap) and *IdentifyingInfo* (IdentifyingInfo) make up the identity of the alarm. All parameters must be according to the alarm definition, i.e. all mandatory parameters should be present, and parameters should have correct value type or be from some predefined range. Addressing the same alarm instance in a clear() or reraise() call is done by making sure that all four values are the same is in the original raise / reraise call.
  39
  40 ## Alarm APIs
  41 * *Raise*: Raises the alarm instance given as a parameter
  42 * *Clear*: Clears the alarm instance given as a parameter, if it the alarm active
  43 * *Reraise*: Attempts to re-raise the alarm instance given as a parameter
  44 * *ClearAll*: Clears all alarms matching moId and appId given as parameters
  45
  46 ## Aux. Alarm APIs
  47 * *SetManagedObjectId*: Sets the default MOId
  48 * *SetApplicationId*: Sets the default AppId
  49
  50
  51 ## Example
  52 -------
  53
  54 ```go
  55 package main
  56
  57 import (
  58         alarm "gerrit.o-ran-sc.org/r/ric-plt/alarm-go.git/alarm"
  59 )
  60
  61 func main() {
  62         // Initialize the alarm component
  63         alarmer, err := alarm.InitAlarm("my-pod", "my-app")
  64
  65         // Create a new Alarm object
  66         alarm := alarmer.NewAlarm(1234, alarm.SeverityMajor, "Some App data", "eth 0 1")
  67
  68         // Raise an alarm (SP=1234, etc)
  69         err := alarmer.Raise(alarm)
  70
  71         // Clear an alarm (SP=1234)
  72         err := alarmer.Clear(alarm)
  73
  74         // Re-raise an alarm (SP=1234)
  75         err := alarmer.Reraise(alarm)
  76
  77         // Clear all alarms raised by the application
  78         err := alarmer.ClearAll()
  79 }
  80 ```
  81
  82 CI
  83 --
  84
  85 The Dockerfile in the `ci` directory _only_ runs, when build, the library unit tests for the repository.
  86
  87 License
  88 -------
  89  Copyright (c) 2020 AT&T Intellectual Property.
  90  Copyright (c) 2020 Nokia.
  91
  92  Licensed under the Apache License, Version 2.0 (the "License");
  93  you may not use this file except in compliance with the License.
  94  You may obtain a copy of the License at
  95
  96      http://www.apache.org/licenses/LICENSE-2.0
  97
  98  Unless required by applicable law or agreed to in writing, software
  99  distributed under the License is distributed on an "AS IS" BASIS,
 100  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 101  See the License for the specific language governing permissions and
 102  limitations under the License.
 103
 104  This source code is part of the near-RT RIC (RAN Intelligent Controller)
 105  platform project (RICP).
 106
 107
 108