This document provides Celona customers with detailed step-by-step description of how to use the Celona Network Monitoring API. We currently support HTTPS-based push and Slack notifications. We are constantly adding new data points to the API. Here is a list of use cases that are currently supported by the monitoring API:
Performance Management: Access Point (AP), Device, Edge State
Coming soon - Application & MicroSlicing Performance metrics, AP/Device Traffic Throughput
Fault Management: Edge Health Alerts
Coming soon - AP and Device Health Stats
Configuring and Subscribing to Notifications
You can configure notification settings and subscribe to various events via REST APIs. All notification APIs sit behind our API gateway. The base path for notification APIs is v1/api/events. Here is the link to detailed API documentation.
All API operations require a valid API key. Any operations without valid API key will be rejected. Notifications APIs are divided into two categories:
Configuration APIs: These APIs are used to configure customer specific settings like certificates, URLs and shared secrets for each notification type. We expect this to be a one-time activity in most cases. The path for the API is
v1/api/events/configure.
Subscription APIs: Once the user has configured the basic settings, they can then use subscription APIs to subscribe/unsubscribe to various events. The path for the API is
v1/api/events/subscription.
How to subscribe to Slack and HTTPS push notifications:
1. Login to Orchestrator to generate an API Key to use with the REST API calls for integration.
2. Make sure to copy and save the API key value as it will not be recoverable or displayed again.
3. Configure customer specific settings using configure API by invoking POST request on https://api.celona.io/v1/api/events/configure. Make sure “X-API-Key” is included in the request as mentioned in step 2.
Configuring settings for Slack notifications
Provide URL, notify_type and customer_id in the body of the request. notify_type should be set to “slack” and the url should be the URL of the channel that you would need to be notified to. For example:
{ "notify_type": "slack",
"url": "<your_slack_url>"
}
Configuring settings for HTTPS push notifications
Provide customer_id, notify_type, url and public_key for your http listener in the body of the request. notify_type should be set to “http” and the url should be the URL of your receiver. For example:
{ "notify_type":"http",
"url":"https://<your_callback_endpoint_url>/",
"public_key: <your_certificate_public_key>"
}
4. Now let's get the list of all supported events to subscribe to. Make sure “X-API-Key” is included in the request as mentioned in step 2.
The response will have the list of events that we currently support
{ "code": 200,
"data": "
["APSTATUS","CPUALERT","DEVICESTATUS","DPALERT","MEMORYALERT","UEALERT"]",
"error": "",
"success": true
}
You should get 200 OK if the above request is successful.
5. Finally, subscribe to an event to receive Slack based notifications by invoking POST operation on https://api.celona.io/v1/api/events/subscription. Make sure “X-API-Key” is included in the request as mentioned in Step 2.
Subscribing an event for Slack notifications
If you would like to subscribe to Slack based notification for MEMORYALERT event, then set notify_type as slack and event_type as “MEMORYALERT”. For e.g.:
{ "event_type": "MEMORYALERT",
"notify_type": "slack"
}
Subscribing an event for HTTP push notifications
Similarly, if you would like to subscribe to http based notification for MEMORYALERT event, then set notify_type as “http” and event_type as “MEMORYALERT”. For e.g.:
{ "event_type": "MEMORYALERT",
"notify_type": "http"
}
You should get 200 OK if the above request is successful.
Currently, the Celona API supports subscribing to only one event at a time. So please make sure that you repeat just the subscription API for multiple events.
6. If you need to un-subscribe to an event, you can invoke DELETE request on the above API. Make sure “X-API-Key” is included in the request as mentioned in Step 2.
Un-subscribing an event from Slack notification
If you want to un-subscribe to slack based notification for MEMORYALERT event, then set notify_type as slack and event_type as “MEMORYALERT”. For e.g.:
{ "event_type": "MEMORYALERT",
"notify_type": "slack"
}
Un-subscribing an event from HTTP push notification
Similarly, If you want to un-subscribe to http based notification for MEMORYALERT event, then set notify_type as “http” and event_type as “MEMORYALERT”. For e.g.:
{ "event_type": "MEMORYALERT",
"notify_type": "http"
}
Event Descriptions
APSTATUS – AP state change (New/Provisioned/Up/Down) notification
{ "event_name": "APSTATUS",
"customer_name": "QAENV",
"cluster_name": "G1-IndoorEdge",
"site_name": "G1-IndoorSite2",
"ap_name": "Indoor03",
"message": "AP's status changed from 'Down' to 'Up'",
"action": "For more diagnostics information, please click the Celona Assistant icon in 'https://qa-cso.celonanetworks.com/#/pages/access-points/1234567890'",
"timestamp": "2021-07-06 19:28:40.219576422 +0000 UTC",
"serial_number": "1234567890",
"ipaddress": "1.1.1.1",
"down_context": "ControlReady",
"previous_status_code": 5,
"current_status_code": 4
} AP status codes
0 - Unknown
1 - New
2 - Pending
3 - Provisioned
4 - Up
5 - Down
6 - DeployedNew- The AP is assigned to a customer and can be added to a site.Pending- The AP is connected to a network before getting assigned to a site.Provisioned– The AP is assigned to a site and ready to be connected to a network (i.e. has not initiated bootstrap).Up- AP is administratively UP, has S1 interface connected with the Edge Cluster, and ready to connect devices.Down- AP is not operational and cannot connect devices. The Down state can be associated with one of thedown_contextshighlighted below.Deployed- The AP is assigned to a site and connected to a network (i.e. has initiated/completed bootstrap).
down_contextcan be one of the following:NoBootstrap
GlobalACSReady
LocalACSReady
SASReady
PendingSASGrant
AdminUp
DownNoBootstrap- AP has not initiated bootstrap process.GlobalACSReady- AP initiated bootstrap process and downloaded configuration from Celona Orchestrator.LocalACSReady- AP reached Celona Edge and downloaded configuration as part of the bootstrap process.SASReady- AP reached Celona Edge, registered with SAS and received spectrum grants from SAS successfully.PendingSAS- AP reached Celona Edge and waiting for spectrum grants from SAS. No channel grants available for this AP.AdminUp- Edge configured AP with available spectrum and it is up.Down- AP is unreachable from Celona Edge.
CPUALERT – Alert to flag that Edge Node CPU utilization exceeded 70%
{
"event_name": "CPUALERT",
"customer_name": "QAENV",
"cluster_name": "ajmay25",
"node_id": "1234567890",
"event_category": "NODECPUSTATS",
"message": "Average CPU utilization (72.788584) exceeded threshold",
"timestamp": "2021-04-20 18:03:50.729 +0000 UTC",
"ipaddress": "1.1.1.1"
}
MEMORYALERT – Alert to flag that Edge Node Memory utilization exceeded 80%
{
"event_name": "MEMORYALERT",
"customer_name": "QAENV",
"cluster_name": "ajmay25",
"node_id": "1234567890",
"event_category": "NODEMEMORYSTATS",
"message": "Memory utilization (87.982452) exceeded threshold. 3.33 GB of total 3.8 GB used",
"timestamp": "2021-04-20 18:13:25.979 +0000 UTC",
"ipaddress": "1.1.1.1"
}
EDGESTATUS – Edge state change (New/Provisioned/Up/Down) notification
{
"event_name": "EDGESTATUS",
"customer_name": "QAENV",
"cluster_name": "ajmay25",
"event_category": "EDGESTATUS",
"event_type": "ALERT",
"message": "Edge status changed from 'Up' to 'Down'",
"action": "Please reach out to support@celona.io for additional information",
"timestamp": "2021-09-16 05:01:51.649 +0000 UTC",
"previous_status_code": 4,
"current_status_code": 5,
"edge_node_info": [
{
"serial_number": "1234567890",
"node_type": "Leader",
"sw_version": "1.1",
"ipaddress": "1.1.1.1",
"node_id": "1234567890",
"current_status_code": 5,
"previous_status_code": 4
}
]
}
Edge status codes
1 - New
2 - Pending
3 - Provisioned
4 - Up
5 - Down
8 - UnreachableNew– Edge is assigned to a customer and can be added to a cluster or site.Pending– Edge is connected to the network but not assigned to a cluster or site.Provisioned– Edge is assigned to a cluster or site and ready to be connected to the network.Up– Edge is connected to the network and reachable from the Orchestrator.Down– Edge may not be connected to the network or not reachable from the Orchestrator.Unreachable- Edge is not reachable from the Orchestrator.
DEVICESTATUS – Device State change notification (New/Provisioned/Up/Down)
{
"event_name": "DEVICESTATUS",
"customer_name": "QAENV",
"timestamp": "2021-03-06 01:55:10.670098817 +0000 UTC",
"message": "Device Status changed from 'Provisioned' to 'Activated",
"previous_status_code": 2,
"current_status_code": 3
"imsi": "1234567890"
}Device status codes
0 - Unknown
1 - New
2 - Provisioned
3 - Activated
4 - Deactivated
5 - Connected
6 - Idle
7 - Disconnected
8 - BlockedNew– The unassigned SIM in the Celona device inventory.Provisioned– The SIM is assigned to a Celona Orchestrator account and can be activated to connect to the Celona network.Activated– The SIM is active and exists in the Celona Edge database. It has not yet connected to the Celona network. It is allowed to connect to the network and consume network services as per the user profile.Deactivated– The SIM is disabled and exists in the Celona Edge database. It cannot connect to the network and user data sessions are not allowed.Retired– The SIM is deactivated and has been removed from Celona Edge database. All assigned profiles have been removed from the Orchestrator.Connected– The SIM is currently connected to the Celona network and has active data sessions from client devices.Idle– The SIM is currently connected to the Celona network but has no active data sessions from client devices.Disconnected– The SIM is active but not connected to the Celona network.Blocked/Suspended– The SIM is blocked from connecting to the Celona network and all user data sessions have been removed from Celona Edge.
DPALERT – Alerts to flag Domain Proxy related errors
{
"event_name": "DPALERT",
"customer_name": "QAENV",
"cluster_name": "G1-IndoorEdge",
"site_name": "G1-IndoorSite2",
"ap_name": "Indoor03",
"event_category": "DPALERT",
"alert_context": "TERMINATEDSTATE",
"message": "Grant ABCD was only AUTHORIZED until 2021-07-06T09:32:06.449896469-07:00; this heartbeat was received after that time, but the CBSD reported AUTHORIZED",
"timestamp": "2021-07-06 16:33:17.565 +0000 UTC",
"serial_number": "1234567890",
"channel_number": "0",
"ipaddress": "1.1.1.1",
"enb_ip_address": "2.2.2.2"
}alert_contextvalues could be one of the following:SUSPENDEDSTATE
TERMINATEDSTATE
NOSPECTRUM
CPIERROR
CBSDBLACKLIST
FORCEDREREGISTER
SUSPENDEDSTATE- This alert is triggered when a channel granted to an AP is suspended by SAS because AP is deployed in a location with incumbent activity. All grants that cause too much interference to Navy operations are suspended. Note - In a suspended state the AP channel can recover post the 'temporary' Incumbent activityTERMINATEDSTATE- This alert is triggered when a channel granted to an AP is terminated. This happens when a channel allocated to Priority Access License (PAL) holder is activated or an incumbent is nearby. Celona Domain Proxy service will attempt to reallocate a new channel to the AP from the available channels. Note - In a terminated state, the AP channel will not auto-recover. Please reach out tosupport@celona.ioto help recover the AP with an alternate channel plan. We are actively working on automating recovery from SAS terminations and minimizing any disruptions to the network. This feature is targeted for production roll out by end of June.NOSPECTRUM- This alert is triggered when an AP has no spectrum available at that location. This is not commonly seen except for locations in Hawaii.CPIERROR- This alert is triggered when the CPI parameters or the CPI certificate/installer credentials entered are incorrect.CBSDBLACKLIST- This alert is triggered when a specific AP has been blacklisted by SAS. This is a precautionary alert and hasn’t been observed yet.FORCEDREREGISTER- When a registered AP needs to be reset to get new grants or needs to move from one location to another, this alert will be triggered as the AP will be deregistered and re-registered.
UEALERT – Alerts to flag Device connectivity errors
{
"event_name": "UEALERT",
"customer_name": "QAENV",
"cluster_name": "G1-OutdoorEdge",
"event_category": "UEALERT",
"alert_context": "IMSIATTACHFAIL",
"message": "1234567890",
"timestamp": "2021-06-12 16:20:06.272 +0000 UTC",
"imsi": "1234567890"
}alert_contextvalues could be one of the followingINVALIDPLMNID
IMSINOTPRESENT
IMSIAUTHFAIL,
IMSIATTACHFAILINVALIDPLMNID- This alert is triggered when the PLMN ID in the UE connection request is not in our configured value. eNB itself will check for valid PLMN ID, so we will not see this alertIMSINOTPRESENT- This alert is triggered when the IMSI is not in the configured devices list (or present in the device list but not activated)IMSIAUTHFAIL- This alert is triggered when the verification of the SIM fails, most likely the SIM was incorrectly read by the device (due to any physical damage of the skin)IMSIATTACHFAIL- This is a generic alert when a valid SIM failed to connect properly due to several other internal errors on the edge
To learn about Celona's unique MicroSlicing technology and how to setup MicroSlicing policies, take a look at our article here.