This Fault Management RESTCONF API tutorial documents a new API method introduced in NSP 24.4, that allows external users to create alarms in the NSP FM system.
Typically, as is the case with most other POST requests, the new method will require a basic list of mandatory alarm values to be included. These are defined in the body of the RESTCONF POST request. The purpose of the tutorial is to explain the implementation of the new method, and the allowable values that may be defined in the specific alarm properties.
Externally created alarms generated through this method will be visible in the NSP FM GUI application , assuming the request is successful.
Actions applicable to externally created alarms are equally relevant as they are for internally generated NSP alarms, for example, alarm acknowledgment, severity change, alarm deletion .. etc. Externally created alarms will also be sent as notifications ( of type alarm-create ) via the Kafka NSP-FAULT-YANG notification topic ( also NSP-FAULT )
Example request/responses are also included with a postman collection.
The alarm creation method uses the following POST request:
POST https://{{server}}:8545/restconf/data/nsp-fault:alarms/alarm-list
The following example demonstrates the mandatory properties, and are provided as a working example, the values specified in the body of the request :
Body
{
"nsp-fault:alarm" : [
{
"perceived-severity": "warning",
"alarm-type-qualifier": "TestTaskOverload",
"probable-cause-string": "outOfCPUCycles",
"alarm-type-id": "communicationsAlarm",
"resource": "fdn:app:external:test-md-node2:default",
"affected-object-type": "ExternalSystem",
"affected-object-name": "test-md-node2",
"alt-resource": "test-md-node2:default/TestTaskOverload"
}
]
}As is usual for NSP RESTCONF API queries, the request requires a valid authentication token specified in the header of the request.
The above example is for an alarming object resource "test-md-node2:default". This is not an alarming object managed natively by NSP. This is a perfectly valid use case of this API method. With this method, it is not mandatory that the object exists within the NSP model for an alarm to be created.
It is intended as part of this API design, that externally created alarms may be implementing their own proprietary alarm definitions. For example, externally created alarms can specify their own object resource naming convention. Provided that the necessary syntax rules ( see Input Properties table below ) are followed, these fields can represent alarming objects ( the resource ) unknown to NSP. This also applies to alarm names ( the alarm-type-qualifier ), they do not have to align with values used in NSP's internally managed alarm definitions. In other words, both these properties can be used to allow modelling of alarming object entities outside of the NSP model. Raising alarms against NSP managed objects is not recommended or supported, especially in a live deployment, even though the NSP application does allow the possibility.
The probable-cause-string value, alarm-type-id and perceived-severity are strict values, and need to align to the NSP alarm modelling guidelines.
These values are defined in the RESTCONF FM nsp-fault.yang module ( fault-management.zip. ) published on the NSP developer portal API documentation page, see the following link for more information: https://network.developer.nokia.com/api-documentation
Note: alarms created externally in the RESTCONF FM API will be visible in the NSP FM GUI, the RESTCONF FM NSP-FAULT-YANG Kafka topic , and also the REST FM NSP-FAULT Kafka topic . This method has the potential to impact clients/vendor notifications inadvertently, any user generated alarms injected into the system needs to consider this fact.
Externally created alarms require the source-system to be specified as "fdn:app:external". When the source-system is not specified, the alarm source-system value will be populated as "fdn:app:external". For any NBI clients not wishing to process such data, a possible approach is to suppress this source-system value in the Kafka consumer property filter.
It is highly recommended that the alt-resource ( the alarm object full name ) is unique, otherwise an exception is returned during the alarm creation attempt, if for example, a second attempt was performed to send the same request without modification of the alt-resource value, this would trigger the exception during validation of the request.
Externally raised alarms created through this API, when successful, will return a 201 response code.
The alarm object created isn't sent as part of the 201 response.
Note: whilst response 201 normally indicates a successful operation, if alarm squelching is enabled, the alarm will not be raised in the NSP FM application. The NSP-FAULT-YANG Kafka consumer can be used to verify successful creation.
The generic RESTCONF POST nsp-inventory:find method can also be used to retrieve an externally created alarm object by specifying the alt-resource property ( the alarm object full name ) in the xpath-filter, for example:
POST https://{{server}}:8545/restconf/operations/nsp-inventory:find
Body
{
"input" : {
"xpath-filter": "/nsp-fault:alarms/alarm-list/alarm[source-system = 'fdn:app:external' and alt-resource='test-md-node2:default/TestTaskOverload']"
}
}The inclusion of the additional source-system is an additional safeguard to ensure that solely the alarm created externally, is received. However, provided the alt-resource is uniquely assigned ( a recommendation for external alarm creation on NSP modelled objects ), it may suffice to only specify the alt-resource in the xpath-filter.
In the above sample, the potential for error due to non-unique alt-resource assignment, is solved by appending the unique alarm-type-qualifier ( the alarm name ) after the equipment port identifier.
As a general recommendation, this is a sound approach to ensuring that the alarm object full name ( alt-resource ) will be valid for alarm creation success.
The externally created alarm will always have the "fdn:app:external" value assigned to the source-system.
This means that if a FM RESTCONF API / FM GUI user wanted to find alarms raised against a specific resource object name, it is possible to just retrieve only the externally created alarms, all alarms, or only NSP internally created alarms, by specifying the source-system value in the xpath-filter.
The external alarm create API method allows the affected-object-type to be loosely defined, and this may be useful for alarms for external systems, unknown to NSP.
For alarms raised on external objects, the affected-object-type should not begin with '/' nor contain any period
Table - Input Properties
| Property |
|
|
|
| source-type |
|
|
|
| source-system |
|
|
|
| perceived-severity |
|
|
|
| alarm-type-qualifier |
|
|
string length up to 4096 |
| probable-cause-string |
|
|
|
| alarm-type-id |
|
|
|
| additional-text |
|
|
|
| ne-id |
|
|
|
| ne-name |
|
|
|
| resource |
|
|
|
| affected-object-type |
|
|
|
| affected-object-name |
|
|
|
| time-created |
|
|
|
| last-raised |
|
|
|
| implicitly-cleared |
|
|
|
| alt-resource |
|
|
|
Timestamp fields, last-raised and time-created must use ISO8601 format. These would need to be converted if the external alarm timestamp values were in another format ( eg: epoch etc )
The implicitly-cleared property cannot be set to true, if specified in the request. This means that alarms created externally will remain in the NSP FM alarms list. They will either need to be deleted using an API request, or from within the FM application. Alarm policies will be created within NSP FM for externally created alarms, and they can also be aged/expired like any other internally created alarm.
Please see the attached postman collection, with sample requests/responses.
It should be understood the importance of ensuring consistent alarm definitions when raising alarms against external resource objects. These externally created alarms will co-exist with alarms from other source types, and may be visible to other FM users. For consistency of implementation, it is recommended that external alarm API users become familiar with the sample responses available in the FM RESTCONF API postman collections. The FM REST API postman collections may also be useful.
Creating large amounts of alarms through this API may impact performance. Nokia Product Line Management has determined that this alarm rate should exceed no more than 5 alarms per hour
FM external alarm creation users can also refer to the inventory tutorials section of the NSP developer portal for more information about the NSP model.