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 directory that is searched by default, usually something like /usr/local/lib.
The alarm feature opens a direct connection to the alarm manager using the RMR library’s wormhole feature, taking the host name and port number from environment variables defined as the constants ALARM_MGR_SERVICE_NAME_ENV and ALARM_MGR_SERVICE_PORT_ENV in the ricxappframe.alarm.alarm module. The message type is set to constant RIC_ALARM_UPDATE in the ricxappframe.alarm.alarm module, currently 110.
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. The alarm target host and port are set by environment variables. The alarm message contents 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: 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: 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 directly to an Alarm Adapter. Requires environment variables ALARM_MGR_SERVICE_NAME and ALARM_MGR_SERVICE_PORT with the destination host (service) name and port number; raises an exception if not found.
- Parameters:
- vctx: ctypes c_void_p
Pointer to RMR context obtained by initializing RMR. The context is used to allocate space and send messages.
- 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: AlarmSeverity, identifying_info: str, additional_info: str = '')[source]¶
Convenience method that creates an alarm instance, an AlarmDetail object, using cached values for the 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: 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: 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: 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
}
}
}