RIC Alarm API¶
Overview¶
The xapp python framework provides an alarm feature in the python subpackage ricxappframe.alarm. This subpackage defines objects and methods for creating, raising and clearing alarms.
The alarm feature reuses the ricxappframe.rmr subpackage for transporting alarm messages. That in turn requires the RMR shared-object library to be available in a system library that is searched by default, usually something like /usr/local/lib.
The alarm feature sends messages using RMR message type RIC_ALARM_UPDATE in the ricxappframe.alarm.alarm module, currently value 13111. The Xapp’s routing table must have one (or more) entries for that message type.
The complete API for the Alarm feature appears below.
Example Usage¶
Alarms are created, raised and cleared using an AlarmManager as shown below. The manager requires an RMR context at creation time.
from ricxappframe.alarm import alarm
from ricxappframe.rmr import rmr
rmr_context = rmr.rmr_init(b"4562", rmr.RMR_MAX_RCV_BYTES, 0x00)
alarm_mgr = alarm.AlarmManager(rmr_context, "managed-object-id", "application-id")
alarm3 = alarm_mgr.create_alarm(3, alarm.AlarmSeverity.DEFAULT, "identifying", "additional")
success = alarm_mgr.raise_alarm(alarm3)
Alarm API¶
Provides classes and methods to define, raise, reraise and clear alarms. All actions are implemented by sending RMR messages to the Alarm Adapter that comply with the JSON schema in file alarm-schema.json.
-
class
ricxappframe.alarm.alarm.AlarmDetail(managed_object_id: str, application_id: str, specific_problem: int, perceived_severity: ricxappframe.alarm.alarm.AlarmSeverity, identifying_info: str, additional_info: str = '')[source]¶ An alarm that can be raised or cleared.
Parameters: - managed_object_id: str
The name of the managed object that is the cause of the fault (required)
- application_id: str
The name of the process that raised the alarm (required)
- specific_problem: int
The problem that is the cause of the alarm
- perceived_severity: AlarmSeverity
The severity of the alarm, a value from the enum.
- identifying_info: str
Identifying additional information, which is part of alarm identity
- additional_info: str
Additional information given by the application (optional)
-
class
ricxappframe.alarm.alarm.AlarmManager(vctx: ctypes.c_void_p, managed_object_id: str, application_id: str)[source]¶ Provides an API for an Xapp to raise and clear alarms by sending messages via RMR, which should route the messages to an Alarm Adapter.
Parameters: - vctx: ctypes c_void_p
Pointer to RMR context obtained by initializing RMR. The context is used to allocate space and send messages. The RMR routing table must have a destination for message type RIC_ALARM_UPDATE as defined in this module.
- managed_object_id: str
The name of the managed object that raises alarms
- application_id: str
The name of the process that raises alarms
-
create_alarm(specific_problem: int, perceived_severity: ricxappframe.alarm.alarm.AlarmSeverity, identifying_info: str, additional_info: str = '')[source]¶ Convenience method that creates an alarm instance, an AlarmDetail object, using cached values for managed object ID and application ID.
Parameters: - specific_problem: int
The problem that is the cause of the alarm
- perceived_severity: AlarmSeverity
The severity of the alarm, a value from the enum.
- identifying_info: str
Identifying additional information, which is part of alarm identity
- additional_info: str
Additional information given by the application (optional)
Returns: - AlarmDetail
-
raise_alarm(detail: ricxappframe.alarm.alarm.AlarmDetail)[source]¶ Builds and sends a message to the AlarmAdapter to raise an alarm with the specified detail.
Parameters: - detail: AlarmDetail
Alarm to raise
Returns: - bool
True if the send succeeded (possibly with retries), False otherwise
-
clear_alarm(detail: ricxappframe.alarm.alarm.AlarmDetail)[source]¶ Builds and sends a message to the AlarmAdapter to clear the alarm with the specified detail.
Parameters: - detail: AlarmDetail
Alarm to clear
Returns: - bool
True if the send succeeded (possibly with retries), False otherwise
-
reraise_alarm(detail: ricxappframe.alarm.alarm.AlarmDetail)[source]¶ Builds and sends a message to the AlarmAdapter to clear the alarm with the the specified detail, then builds and sends a message to raise the alarm again.
Parameters: - detail: AlarmDetail
Alarm to clear and raise again.
Returns: - bool
True if the send succeeded (possibly with retries), False otherwise
Alarm Messages¶
Alarm messages conform to the following JSON schema.
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/alarm-go.json",
"type": "object",
"title": "Alarm schema",
"description": "Schema for RIC alarm messages.",
"default": {},
"examples": [
{
"managedObjectId": "my-pod-lib",
"applicationId": "my-app",
"specificProblem": 1234,
"perceivedSeverity": "MAJOR",
"additionalInfo": "Some App data",
"identifyingInfo": "eth 0 1",
"AlarmAction": "RAISE",
"AlarmTime": 1591188407505707
}
],
"required": [
"managedObjectId",
"applicationId",
"specificProblem",
"perceivedSeverity",
"identifyingInfo",
"AlarmAction",
"AlarmTime"
],
"additionalProperties": true,
"properties": {
"managedObjectId": {
"type": "string",
"title": "The managedObjectId schema",
"description": "The name of the managed object that is the cause of the fault.",
"default": ""
},
"applicationId": {
"type": "string",
"title": "The applicationId schema",
"description": "The name of the process that raised the alarm.",
"default": ""
},
"specificProblem": {
"type": "integer",
"title": "The specificProblem schema",
"description": "The problem that is the cause of the alarm.",
"default": 0
},
"perceivedSeverity": {
"type": "string",
"enum": [
"UNSPECIFIED",
"CRITICAL",
"MAJOR",
"MINOR",
"WARNING",
"CLEARED",
"DEFAULT"
],
"title": "The perceivedSeverity schema",
"description": "The severity of the alarm.",
"default": ""
},
"additionalInfo": {
"type": "string",
"title": "The additionalInfo schema",
"description": "Additional information given by the application (optional).",
"default": ""
},
"identifyingInfo": {
"type": "string",
"title": "The identifyingInfo schema",
"description": "Identifying additional information, which is part of alarm identity.",
"default": ""
},
"AlarmAction": {
"type": "string",
"enum": [
"RAISE",
"CLEAR",
"CLEARALL"
],
"title": "The AlarmAction schema",
"description": "Action to perform on the alarm.",
"default": ""
},
"AlarmTime": {
"type": "integer",
"title": "The AlarmTime schema",
"description": "Current system time in milliseconds since the Epoch.",
"default": 0
}
}
}