Overview


Monitoring of a production environment can be a critical aspect for any business.  Knowing when there is an issue quickly and in many cases taking action on an issue via automation can be key to business continuity.  To address these situations and prevent users from losing visibility to valuable metrics when shifting to a IaaS setup, Pureport has surfaced several metrics via the API that is accessible to the end users.  The API is available for monitoring tools and agents to query, alert on, and even automate responses.  


This article will go over the available API calls and at a very high level discuss the values and some ways to leverage them for monitoring.  Since each monitoring tool is different, and the monitoring needs of each business is different, it is recommend to use this article as a reference and tune your production monitoring to your business's needs.


Pre-requisites


  • A general understanding of how API's work
  • An existing monitoring tool able to query an HTTPS REST API
  • A general understanding of how your monitoring tool can be configured to query REST API's and process JSON output
  • A Pureport account with access to the API
  • An API Key and Secret (If not already created, more on this can be found at The Pureport API)


Steps


The Pureport API surfaces metrics for each gateway used in your network individually.  For accuracy and complete monitoring be sure to monitor each gateway in use.  Metrics are pulled based on the gateway ID, which can be found via the API by listing the details of each connection, or via the Pureport Console.


The following steps will walk through the process to identify the Gateway ID via the Console.


  1. Log into the Pureport console
  2. Select the network you wish to monitor by clicking on Networks and the Network name.

  3. Select the Connection you are wishing to monitor

  4. Scroll down to the Gateway(s) associated to the connection and copy the value listed in the ID for each Gateway.

    Note: HA connection will have a Primary and Secondary gateway.  You will need to capture the Gateway ID for each gateway.


  5. Repeat steps 3-4 for each connection on the network you wish to monitor making note of each Gateway ID and the associated connection

Once the Gateway ID's have been captured for each of the gateways, you will need to configure your monitoring tool to access the Pureport API and record the metrics.  Metrics will be returned in JSON format.

  • Setup your monitoring tool so it can access the Pureport API using your API Key and Secret.  The Pureport API can be found at https://api.prd.pureport.com/
  • If not already created, you can manage your API keys via the Pureport Console's API Keys Section


Next, configure your monitoring tool to pull the metrics for each of the gateways on a recurring interval. Metrics for each gateway can be pulled using the the following API call.  Be sure to update the "<Gateway_ID>" section of the API call with the ID(s) gathered in step 4 to reflect the Gateway you are wishing to monitor.  You will need to make this API call for each gateway ID on each connection you wish to monitor.


https://api.prd.pureport.com/gateways/<Gateway_ID>/metrics/connectivity/current


Results from the API will be returned in JSON format and contain the metrics of the most recent ping test from the gateway at the time of the API call.

[
{
"gateway": {
"id": "<Gateway_ID>",
"href": "/gateways/<Gateway_ID>"
},
"time": {
"start": "<Current Date and Time>",
"end": "<Current Date and Time>"
},
"destinationAddress": "##.##.##.##",
"lossRate": 0,
"average": 0.0013919120000000001,
"min": 0.0012221340000000002,
"max": 0.001675844,
"standardDeviation": 0.150187
}
]


The following Metrics can be used for monitoring health and connectivity of the gateway. All of these metrics are a measurement of Ping tests from the gateway to the destination address listed in the results (this is the endpoint on the other end of the connection being monitored):

  • lossRate - Reports the loss measure on the connection 
  • average - Average Ping time of the the connection test
  • min - Minimum Ping time of the connection test
  • max - Maximum Ping time of the connection test
  • standardDeviation - Deviation of results from the current ping test.


Based on the monitoring requirements of your business, these metrics can be used to validate that a connection is active and performing at desired performance level.  Many businesses will monitoring the average ping values of the connection as well as the loss rate. 


Note:  Many networks set pings as a lower priority traffic type.  It is recommend to configure your monitoring tool in a sliding window method to "smooth" any one-off variations and minimize false alarms.


Additional Metrics to consider


While the above mentioned metrics will get you detailed analysis about the health of each connection, there is additional value in monitoring status' at a higher level.  Below are a few recommendations:

  • Gateway status

  • BGP peering status

  • IPSEC connection status (If using a Site-Connect VPN)


Each of these components can be pulled via an API call for each Gateway ID (as captured in Step 4 above) and monitored by a 3rd party tool for expected values.  Below we will look at the recommended API call, as well as the output of that call and explore the values that correlate to the above mentioned metrics.


Each Gateway Status can be monitored using the following API call, be sure to update the <Gateway_ID> with the ID of the gateway you are wishing to monitor:

https://api.prd.pureport.com/gateways/<Gateway_ID>/details


The Pureport API Platform will return the following JSON values for this call. Note: Some values have been updated with descriptions for this document.

{
  "id": "Gateway_ID",
  "type": "Gateway_Type",
  "availabilityDomain": "PRIMARY",
  "name": "Name",
  "state": "Gateway_State",
  "bgpConfig": {
    "state": "BGP_State",
    "peeringSubnet": "169.254.0.0/30",
    "pureportIP": "169.254.0.1/30",
    "pureportASN": 394351,
    "customerIP": "169.254.0.2/30",
    "customerASN": 65000
  },
  "version": "Gateway_Version",
  "connection": {
    "id": "Associated_Connection_ID",
    "href": "/connections/Connection_ID",
    "title": "Main Office"
  },
  "pureportInternalGatewayIP": "Internal_Gateway_IP",
  "pureportGatewayIP": "Public_IP_Address",
  "customerGatewayIP": "VPN_IP",
  "pureportVtiIP": "VTI_IP_Address",
  "customerVtiIP": "VTI_IP_Address",
  "auth": {
    "type": "PSK",
    "key": "********************************"
  },
  "ipsecStatus": "IPsec_Status",
  "osServerId": "",
  "osInsidePortId": "",
  "osOutsidePortId": "",
  "href": "/gateways/Gateway_ID"
}


Within this response you will find many useful details pertaining to the gateway. The main components we are looking to monitor within this call are the following:

  • State of the Gateway - Status of the gateway associated with the connection. 
    •  API Value
      •  "state": "Gateway_State
    • Possible Values for "Gateway_State"(String)
      • WAITING_TO_PROVISION
      • PROVISIONING
      • FAILED_TO_PROVISION
      • ACTIVE
      • DOWN
      • UPDATING
      • FAILED_TO_UPDATE
      • DELETING
      • FAILED_TO_DELETE
      • DELETED
  • State of BGP Peering - Status of the BGP peering session 
    • API Value
      • "state": "BGP_State"
    • Possible Values for "BGP_State" (String)
      • UP
      • DOWN
      • PENDING
  • State of VPN connection - Status of the IPsec connection  (If applicable) 
    • API Value
      • "ipsecStatus": "IPsec_Status"  
    • Possible Values for "IPsec_Status"(String)
      • CREATED
      • CONNECTING
      • ESTABLISHED
      • PASSIVE
      • REKEYING
      • REKEYED
      • DELETING
      • DESTROYING
      • DOWN

  

Your Business and Monitoring needs will dictate what should be monitored and how often from the above list.  Keep in mind that it is recommended that any monitoring be created as a "Sliding window" to prevent false alarms caused for normal operational changes or potential missed poling cycles.

The API can also be leveraged for taking actions on alerts.  Be sure to reference the API Reference Page in the Pureport Console for a list of the most current API actions that can be used for your automation needs.

References


  • The API section of the console has a wealth of knowledge available for the API.  Be sure to log in to your account and navigate to the API section:
    • Getting Started: Will provide you an overview and basic steps to begin using the API
    • API Keys will allow you to manage your existing and create new API keys for you account
    • Reference:  Presents the most current Pureport API Swagger.  This will allow you view, validate, and try API calls via an interactive GUI.
      Note:  This GUI  is not a demo or non-production view, it is a live API tool for your current account, use caution on executing commands as it will be performed against your existing setup 
  • The Pureport API