Session State and Threshold Crossing Notifications over RESTCONF

RESTCONF State and Threshold Alert Notifications

The Provider Connectivity Assurance system delivers notifications over RESTCONF for two main event categories.

• State changes: for endpoints and sessions
• Threshold crossing alerts: for services with attached sessions

State Changes

Whenever the state of a managed service-endpoint or session changes, PCA sends a RESTCONF notification of the event. This enables users of the RESTCONF/YANG interface to respond to these state changes to, for example, refresh a user view to display sessions that are in a non-running state.

Threshold Crossing Alerts

Threshold Crossing alerts can be configured and act on session metrics, for example, to alert if packet loss or latency exceeds a specified threshold. The YANG model offers the following alert conditions:

The “metrics-direction” parameter is used to set the directionality for the metrics, with values specified in the table below:

The “alert-severity” parameter is used to set the severity of the alert, with one of the following values:

critical
major
minor

The “triggers-on” parameter is used to define the criteria for threshold crossing, along with the “threshold” and “comparator” parameters.

"triggers-on":{
                         "threshold":"1000.0",
                         "comparator":"gte"
                       }

The “recovers-on” parameter is used to specify the clear condition in a similar manner:

"recovers-on":{
                           "threshold":"1000.0",
                           "comparator":"lt"
                         }

The following comparators are available:

Configuration of Alert Policies via RESTCONF YANG

Alert policies in Provider Connectivity Assurance are described in detail in the Alert Policies article.

To define and reference a new alert policy using the RESTCONF interface, you must first create the policy. Below is an example of a POST request to create a new policy that ensures the delay-max does not exceed 1000 microseconds:

        data RESTCONF POST :: /restconf/data/Accedian-alert:alert-policies
             {
                 "Accedian-alert:alert-policy":[{
                     "policy-id":"alert-example-1",
                     "policy-name":"alert-example-1",
                     "policy-type":"Accedian-alert-type:metric",
                     "policy":{
                         "Accedian-alert-metric:metric-policy":{
                             "conditions":[{
                                 "condition-id":"alert_rule1",
                                 "metric-type":"delay-max",
                                 "alert-direction":"ds",
                                 "alert-severity":"critical",
                                 "triggers-on":{
                                     "threshold":"1000.0",
                                     "comparator":"gte"
                                 },
                                 "recovers-on":{
                                     "threshold":"1000.0",
                                     "comparator":"lt"
                                 }
                             }]
                         }
                     }
                 }]
             }

Create the Same Policy Using Cisco NSO

devices device skylight
 config
  alert-policies alert-policy alert-example-1 
   policy-name alert-example-1
   policy-type metric
   policy metric-policy conditions alert_rule1
    metric-type     delay-max
    alert-direction ds
    alert-severity  critical
    triggers-on threshold 1000.0
    triggers-on comparator gte
    recovers-on threshold 1000.0
    recovers-on comparator lt
   !
  !

After creating an alert policy, it can be referenced when setting up new services that must be validated against this policy. Currently, you cannot PATCH the alert association to an existing service. Therefore, to reference a new alert policy for an existing service, you must delete the service and recreate it with the correct alert policy reference.

Below is an example of a RESTCONF request to associate the policy “alert-example-1” when creating a new service:

             RESTCONF POST :: /restconf/data/Accedian-service:services
             {
                 "Accedian-service:service":[{
                     "service-id":"example-service",
                     "service-name":"example-service",
                     "description":"hello",
                     "sessions":[{
                         "session-id":"example-twamp-1"
                     }],
                     "metadata":{
                         "key-value":[{
                             "key-name":"region",
                             "value":"Nordics"
                         }]
                     },
                     "alerts":[{
                         "alert-policy-id":"alert-example-1"
                     }]
                 }]
             }

Reference YANG Tree for Alert Policy and Metrics

The YANG tree for the threshold crossing alert definition is below:

module: Accedian-alert
  +--rw alert-policies
     +--rw alert-policy* [policy-id]
        +--rw policy-id      string
        +--rw policy-name?   string
        +--rw description?   string
        +--rw policy-type    identityref
        +--rw policy
        
module: Accedian-alert-metric
  augment /acdal:alert-policies/acdal:alert-policy/acdal:policy:
    +--rw metric-policy
       +--rw conditions* [condition-id]
          +--rw condition-id       string
          +--rw metric-type?       acdalmet:metric-type
          +--rw alert-direction?   acdalmet:metric-direction
          +--rw alert-severity?    acdalt:alert-severity
          +--rw triggers-on
          |  +--rw threshold?      decimal64
          |  +--rw comparator?     comparator
          |  +--rw duration-sec?   uint32
          |  +--rw ratio?          uint8
          +--rw recovers-on
             +--rw threshold?      decimal64
             +--rw comparator?     comparator
             +--rw duration-sec?   uint32
             +--rw ratio?          uint8
  augment /acdal:alert-notification/acdal:alert-data:
    +-- metric
       +-- type?        acdalmet:metric-type
       +-- direction?   acdalmet:metric-direction
       +-- value?       string

Subscribing to RESTCONF Notifications for State and Alerts

Users can subscribe to all notifications or choose specific service-endpoints or sessions by using the optional “group-id” parameter for services and sessions.

Below are examples using Cisco NSO to interact with the YANG interface.

Subscribe to All Alert Notifications on the System

admin@ncs(config)# devices device skylight
admin@ncs(config-device-skylight)# notifications subscription alert_notif stream notification-stream/Accedian-alert:alert-notification local-user admin

Subscribe to State Notifications for All Sessions

admin@ncs(config)# devices device skylight
admin@ncs(config-device-skylight)# notifications subscription my_sessions_state stream notification-stream/Accedian-session:state-change-event local-user admin

Subscribe to State Notifications for All Service-endpoints

admin@ncs(config)# devices device skylight
admin@ncs(config-device-skylight)# notifications subscription my_services_state stream notification-stream/Accedian-service-endpoint:state-change-event local-user admin

Check Existing Notification Subscriptions

admin@ncs# show devices device skylight notifications subscription status
notifications subscription alert_notif
 status running

View Received Notifications

admin@ncs# show devices device skylight notifications received-notifications

notifications received-notifications notification 2024-10-22T10:31:35.82347+00:00 0
user          admin
subscription  test1
stream        notification-stream/Accedian-alert:alert-notification
received-time 2024-10-22T10:31:35.971903+00:00
data alert-notification policy-id policy\_t1
data alert-notification condition-id cond\_t1
data alert-notification session-id ahihihi\_agent-test1
data alert-notification service service-id service-id\_test1
data alert-notification alert-state raised
data alert-notification timestamp 2024-10-22T10:28:18+00:00
data alert-notification alert-severity critical
data alert-notification alert-type metric
notifications received-notifications notification 2024-10-22T10:34:31.212698+00:00 0
user          admin
subscription  test1
stream        notification-stream/Accedian-alert:alert-notification
received-time 2024-10-22T10:34:31.356099+00:00
data alert-notification policy-id policy\_t1
data alert-notification condition-id cond\_t1
data alert-notification session-id ahihihi\_agent-test1
data alert-notification service service-id service-id\_test1
data alert-notification alert-state cleared
data alert-notification timestamp 2024-10-22T10:28:18+00:00
data alert-notification alert-severity critical
data alert-notification alert-type metric