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