Service Health RESTCONF Notifications
- RESTCONF Notifications for Service Health
1. Introduction
Crosswork’s RESTCONF SSE notification enables you to proactively identify issues with customer-facing services and improve customer experience. The notification contains the name of the affected service, the health of the service(for example, “Down” or “Degraded"), timestamp at the which the issue was detected, the severity level of the change, and symptoms. After you fix the issue and restore the service to a healthy state, the same notification will be cleared.
The following section explains the RESTCONF SSE notification in detail:
2. Service Affecting Notification Data Model
Here is the YANG definition for supported notifications in Service Health.
cisco-crosswork-service-health.yang:
module cisco-crosswork-service-health {
namespace "urn:cisco:params:xml:ns:yang:cw:app:sh";
prefix sh;
organization "Cisco Systems Inc.";
contact "mailto:cnc-support@cisco.com";
description "Example Notification Data Model Module.";
revision "2022-09-13" {
description "Initial version.";
}
import ietf-yang-types {
prefix yang;
}
typedef health-status {
type enumeration {
enum "unknown" {
value 1;
description "Default state displayed by CNC-ISTP, when monitoring is not enabled for a given service.";
}
enum "monitoring-initiated" {
value 2;
description "When a monitoring request is received for a service, Service Health initializes the service or subservice to this state.";
}
enum "monitoring-failed" {
value 3;
description "Indicates Service Health has encountered an internal error or failure.";
}
enum "monitoring-paused" {
value 4;
description "Indicates that monitoring is currently paused, but historical data is still available for inspection through the timeline.";
}
enum "up" {
value 5;
description "At the service level, this state indicates that all the individual subservices of the monitored service are in good health and operating without any issues to report. At the subservice level, this state specifically indicates that the subservice being monitored is healthy.";
}
enum "down" {
value 6;
description "This state indicates that all the different subservices of the Service that is being monitored are reporting issues.";
}
enum "degraded" {
value 7;
description "At the Service level, this state indicates that some of the subservices of the Service that is being monitored are reporting issues. At the subservice level, this state indicates that the subservice being monitored is reporting an issue.";
}
}
}
notification service-health-notification {
description "Service Health Notification";
container service-health-report {
leaf timestamp {
type yang:date-and-time;
description "The timestamp of Service Health report.";
}
leaf service-id {
type string;
description "Service Identity.";
}
leaf status {
type health-status;
description "Service Health status.";
}
leaf error {
type string;
description "The error message (if any).";
}
list subservice-health-reports {
key "subservice-id";
leaf subservice-id {
type string;
description "Subservice identity.";
}
leaf status {
type health-status;
description "Subservice health status.";
}
leaf-list symptom {
type string;
description "Symptom at subservice level.";
}
leaf-list error {
type string;
description "Error at subservice level.";
}
}
}
}
}
Sample Notification Data
Here is a sample notification:
{
"ietf-restconf:notification":{
"cisco-crosswork-service-health:service-health-notification":{
"service-health-report":{
"timestamp":"2021-05-25T22:11:23.947Z",
"status":"degraded",
"service-id":"ietf-l2vpn-ntw:l2vpn-ntw/vpn-services/vpn-service=0-SimL2VPN_NM-EVPN",
"error":"Something is wrong",
"subservice-health-reports":[
{
"subservice-id":"red",
"status":"monitoring-initiated",
"symptom":[
"Dashboard is very hot"
],
"error":[
"P15 happened",
"P11 happened"
]
},
{
"subservice-id":"green",
"status":"monitoring-failed",
"symptom":[
"Service blocked",
"Connection lost"
],
"error":[
"Shutdown happening"
]
}
]
}
}
},
"event-time":"2022-10-16T05:50:06.332796Z"
}
3. NBI endpoint to receive the notification
<https://${host}:30603/crosswork/nbi/cat-inventory/v1/restconf/notif/notification-stream/cisco-crosswork-service-health:service-health-notification/JSON>
4. How to Receive Notifications
The following steps detail how to receive a RESTCONF notification for Service Health in Crosswork Network Controller.
Step 1: Request a Ticket Granting Ticket (TGT)
curl -k -X POST 'https://{cw-server}:30603/crosswork/sso/v1/tickets' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: text/plain' \
--data-raw 'username={username}&password={password}'
Remember to replace {cw-server}, {username} and {password} with real values.
The TGT response will look like the following snippet. This response is used in the next step.
TGT-10-yelMq0H-iO2xjYRtiuqbeD-UM0PsTzqxy-QtQ6lHZi5M8D-S7DKKX0zSjZ-ErwFFOnc-cas-1
Step 2: Request a JWT Service Ticket
Use the TGT from the previous step to request a JWT service ticket.
curl -k -X POST 'https://{cw-server}:30603/crosswork/sso/v1/tickets/TGT-10-yelMq0H-iO2xjYRtiuqbeD-UM0PsTzqxy-QtQ6lHZi5M8D-S7DKKX0zSjZ-ErwFFOnc-cas-1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'service=<https://{cw-server}:30603/app-dashboard>'
The response JWT token looks like below. This response is used in the next step.
eyJhbGciOiJIUzUxMiJ9.eyJjbGllbnRJcEFkZHJlc3MiOiIxMC4yNDQuNTYuMCIsInN1YiI6ImFkbWluIiwiYXV0aEhhbmRsZU5hbWUiOiJRdWVyeURhdGFiYXNlQXV0aGVudGljYXRpb25IYW5kbGVyIiwiaXNGcm9tTmV3TG9naW4iOnRydWUsImF1dGhlbnRpY2F0aW9uRGF0ZSI6IjIwMjMtMDEtMTlUMDQ6NDE6MDguMzI4NjAwWiIsInBvbGljeV9pZCI6ImFkbWluIiwic3VjY2Vzc2Z1bEF1dGhlbnRpY2F0aW9uSGFuZGxlcnMiOiJRdWVyeURhdGFiYXNlQXV0aGVudGljYXRpb25IYW5kbGVyIiwiaXNzIjoiaHR0cHM6XC9cLzEwLjE5NC41Ny4xNTY6MzA2MDNcL2Nyb3Nzd29ya1wvc3NvIiwidXNlckFnZW50IjoiUG9zdG1hblJ1bnRpbWVcLzcuMjkuMiIsImNyZWRlbnRpYWxUeXBlIjoiVXNlcm5hbWVQYXNzd29yZENyZWRlbnRpYWwiLCJhdWQiOiJodHRwczpcL1wvMTAuMTk0LjU3LjE1NjozMDYwM1wvYXBwLWRhc2hib2FyZCIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiUXVlcnlEYXRhYmFzZUF1dGhlbnRpY2F0aW9uSGFuZGxlciIsImdlb0xvY2F0aW9uIjoidW5rbm93biIsInZpcnR1YWxEb21haW5zIjoiUk9PVC1ET01BSU4iLCJzZXJ2ZXJJcEFkZHJlc3MiOiIxMC4yNDQuMjExLjI3IiwibG9uZ1Rlcm1BdXRoZW50aWNhdGlvblJlcXVlc3RUb2tlblVzZWQiOmZhbHNlLCJjaGFuZ2VfcHdkIjoiZmFsc2UiLCJleHAiOjE2NzQxMzIwNzUsImlhdCI6MTY3NDEwMzI3NSwianRpIjoiU1QtMTAtMTZ3ZjNVWDRkZTdudU1xN3FhNzR5dFJVLUtkTHZtSkZtdWRLS2M1dlVlYTNHSE00R3o3TzVZdUdWUG5RMHJRUW92UTJ5UWlqQWJOM1Q4a3dpNm5id0lPd0w1UnE4dzVsbHhMSU1kYnlQTUJucFNiTnhJLTgyQnYyUG9GeGRkaG9uYlYydnZ2b0VXWFFqR1pSMm5EdVF0eWhzRW14MG03TC1jYXMtMSJ9.cy1DkTF-MJduosZMlDF9eC6J8SjGMxNT-5Bhwwwxu2\_VMXk4-cs\_QK6Sp8IbzuYf1TthuOCc4zaWI1VBygFSXg
The following is an example shell command requesting the event streams. Be sure to replace the "Authorization: Bearer" header's contents with the JWT token you acquired in Step 2. You will get a JSON response. You don't need to take any action with respect to the JSON response.
Step 3: Retrieve the list of supported event streams from a RESTCONF server
curl -k -X GET 'https://{cw-server}:30603/crosswork/nbi/cat-inventory/v1/restconf/data/ietf-restconf-monitoring:restconf-state/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {header}'
The following is an example shell command requesting the notification resource. Be sure to replace the "Authorization: Bearer" header's contents with the JWT token you acquired in Step 2. You will get a JSON response. You don't need to take any action with respect to the JSON response.
Step 4: Retrieve the notification resource
curl -k -X GET 'https://{cw-server}:30603/crosswork/nbi/cat-inventory/v1/restconf/data/ietf-restconf-monitoring:restconf-state/streams/stream=service-health-notification/access=JSON/location' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {header}'
The following is an example shell command requesting the event stream. Be sure to replace the "Authorization: Bearer" header's contents with the JWT token you acquired in Step 2. You will get a JSON response. You don't need to take any action with respect to the JSON response.
Step 5: Subscribe to the Service Health notification event stream
curl -k -X GET 'https://{cw-server}:30603/crosswork/nbi/cat-inventory/v1/restconf/notif/notification-stream/cisco-crosswork-service-health:service-health-notification/JSON' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJjbGllbnRJcEFkZHJlc3MiOiIxMC4yNDQuNTYuMCIsInN1YiI6ImFkbWluIiwiYXV0aEhhbmRsZU5hbWUiOiJRdWVyeURhdGFiYXNlQXV0aGVudGljYXRpb25IYW5kbGVyIiwiaXNGcm9tTmV3TG9naW4iOnRydWUsImF1dGhlbnRpY2F0aW9uRGF0ZSI6IjIwMjMtMDEtMTlUMDQ6NDE6MDguMzI4NjAwWiIsInBvbGljeV9pZCI6ImFkbWluIiwic3VjY2Vzc2Z1bEF1dGhlbnRpY2F0aW9uSGFuZGxlcnMiOiJRdWVyeURhdGFiYXNlQXV0aGVudGljYXRpb25IYW5kbGVyIiwiaXNzIjoiaHR0cHM6XC9cLzEwLjE5NC41Ny4xNTY6MzA2MDNcL2Nyb3Nzd29ya1wvc3NvIiwidXNlckFnZW50IjoiUG9zdG1hblJ1bnRpbWVcLzcuMjkuMiIsImNyZWRlbnRpYWxUeXBlIjoiVXNlcm5hbWVQYXNzd29yZENyZWRlbnRpYWwiLCJhdWQiOiJodHRwczpcL1wvMTAuMTk0LjU3LjE1NjozMDYwM1wvYXBwLWRhc2hib2FyZCIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiUXVlcnlEYXRhYmFzZUF1dGhlbnRpY2F0aW9uSGFuZGxlciIsImdlb0xvY2F0aW9uIjoidW5rbm93biIsInZpcnR1YWxEb21haW5zIjoiUk9PVC1ET01BSU4iLCJzZXJ2ZXJJcEFkZHJlc3MiOiIxMC4yNDQuMjExLjI3IiwibG9uZ1Rlcm1BdXRoZW50aWNhdGlvblJlcXVlc3RUb2tlblVzZWQiOmZhbHNlLCJjaGFuZ2VfcHdkIjoiZmFsc2UiLCJleHAiOjE2NzQxMzIwNzUsImlhdCI6MTY3NDEwMzI3NSwianRpIjoiU1QtMTAtMTZ3ZjNVWDRkZTdudU1xN3FhNzR5dFJVLUtkTHZtSkZtdWRLS2M1dlVlYTNHSE00R3o3TzVZdUdWUG5RMHJRUW92UTJ5UWlqQWJOM1Q4a3dpNm5id0lPd0w1UnE4dzVsbHhMSU1kYnlQTUJucFNiTnhJLTgyQnYyUG9GeGRkaG9uYlYydnZ2b0VXWFFqR1pSMm5EdVF0eWhzRW14MG03TC1jYXMtMSJ9.cy1DkTF-MJduosZMlDF9eC6J8SjGMxNT-5Bhwwwxu2\_VMXk4-cs\_QK6Sp8IbzuYf1TthuOCc4zaWI1VBygFSXg'
The notification stream will look like the following example.
: ping
data: {"ietf-restconf:notification":{"cisco-crosswork-service-health:service-health-notification":{"service-health-report":{"timestamp":"2021-05-25T22:11:23.947Z","status":"degraded","service-id":"ietf-l2vpn-ntw:l2vpn-ntw/vpn-services/vpn-service=0-SimL2VPN\_NM-EVPN","error":"Something is wrong","subservice-health-reports":[{"subservice-id":"red","status":"monitoring-initiated","symptom":["Dashboard is very hot"],"error":["P15 happened","P11 happened"]},{"subservice-id":"green","status":"monitoring-failed","symptom":["Service blocked","Connection lost"],"error":["Shutdown happening"]}]}}},"event-time":"2022-10-16T05:50:06.332796Z"}
data: {"ietf-restconf:notification":{"cisco-crosswork-service-health:service-health-notification":{"service-health-report":{"timestamp":"2021-05-25T22:11:23.947Z","status":"degraded","service-id":"ietf-l2vpn-ntw:l2vpn-ntw/vpn-services/vpn-service=0-SimL2VPN\_NM-EVPN","error":"Something is wrong","subservice-health-reports":[{"subservice-id":"red","status":"monitoring-initiated","symptom":["Dashboard is very hot"],"error":["P15 happened","P11 happened"]},{"subservice-id":"green","status":"monitoring-failed","symptom":["Service blocked","Connection lost"],"error":["Shutdown happening"]}]}}},"event-time":"2022-10-16T05:50:06.332796Z"}
: ping