Monitoring with Network Insights API

The Aviatrix Network Insights API allows you to retrieve network metric and status data across your Aviatrix data plane. Using the metric and status APIs, you can integrate with third-party tools for data analysis and visualization of the performance and health of your Aviatrix-managed resources. The APIs also support data retention for compliance.

The Network Insights API supports Prometheus and JSON formats. All data transmissions are encrypted using industry-standard protocols. An API key is used to authenticate requests for your Aviatrix services.

See Metrics Monitored for Aviatrix Resources for a list of the metrics monitored by Aviatrix. The metrics supported by the Network Insights API are identified in the list.

Use of the Aviatrix API requires the Aviatrix Network Insights API add-on license, enabled in CoPilot from Settings > Configuration > License.

Enabling the Network Insights API

To use the Aviatrix API, you need to enable API access to CoPilot and create an authentication key. You will use the key in any scripts you create to scrape metric or status data from CoPilot.

The Aviatrix API uses port 443, the same port as the CoPilot UI. Ensure that port 443 is accessible and not restricted by any Security Groups.
The API key created during this procedure will not be accessible again. Be sure to save it in a secure place. If you need the key later and cannot find it, you will need to reset the key.

  1. In CoPilot, navigate to Settings > Configuration > License.

  2. Scroll to Add-on Features, and then click Enable next to Network Insights API.

  3. Click Enable API Access in the confirmation window to proceed.

  4. Copy the provided API key and save it in a secure place.

  5. Click Download API Specification, and then select Metrics API or Status API to download the associated OpenAPI .yaml specification.

  6. Click Close to exit the window.

If you disable or reset the authorization key, the old key is purged from the system and cannot be retrieved. You must generate a new key.

See Metric API .yaml Specification and Status API .yaml Specification for more information about the files.

screenshot of enabling the Network Insights API license

Downloading API Documentation in CoPilot

If you did not download the API Specification when you enabled the API feature, you can download the specification document from the Configuration page. The Network Insights API card displays on this page only if the feature has been enabled on the License tab.

There are two specification files in OpenAPI .yaml format, one for the metrics API and one for the status API. They provide examples of the information you need to provide in your API scripts and examples of the output from the API.

  1. In CoPilot, navigate to Settings > Configuration > General.

  2. Scroll to the Features section and expand the section, if needed.

  3. Under Network Insights API, select an API specification.

  4. Click Download.

See Metric API .yaml Specification and Status API .yaml Specification for more information about the files.

Resetting the API Key

You can reset the API key from the Configuration page in CoPilot. The Network Insights API card displays on this page only if the feature has been enabled on the License tab.

If you reset the API key, remember to update any scripts that use the old key, to avoid authentication issues.

  1. Navigate to Settings > Configuration > General.

  2. Scroll to the Features section and expand the section, if needed.

  3. Under Network Insights API Key, click Reset API Key.

  4. Select the checkbox for "I understand the implications," and then click Reset.

  5. Copy the key and close the confirmation window.

Using the API Specification Files

The two OpenAPI .yaml files that you can download from CoPilot’s Settings > Configuration page provide examples of the output you can gather by using the Aviatrix Network Insights API. The two files are aviatrix-copilot-metrics-api.yaml and aviatrix-copilot-status-api.yaml.

These specification files also identify the information you need to provide, so you can access CoPilot to collect data using the API.

Metric API .yaml Specification

Following is an example of a metric OpenAPI specification file, with annotations.

openapi: 3.0.3
info:
  title: Aviatrix Metrics API
  version: '1.1'
  description: Descriptions of specific metrics can be found [here](https://docs.aviatrix.com/documentation/latest/monitoring-troubleshooting/metrics-monitor.html)
servers:
  - url: https://{copilotAddress}/metrics-api/v1     (1)
    variables:
      copilotAddress:
        default: CoPilot
        description: CoPilot address
paths:
  /gateways:
    get:
      summary: Retrieves available metrics for gateways and network interfaces
      parameters:
        - name: format
          in: query
          description: Output format. Default is Prometheus
          required: false
          schema:
            type: string
            enum:                                     (2)
              - prometheus
              - json
      responses:
        '200':
          description: Successful operation           (3)
          content:
            application/json:
              example:
                gateway-1-name:
                  '@timestamp': "2023-03-16T18:08:20.000Z"
                  memory_cached: 210653
                  memory_buf: 29491
                  memory_swpd: 0
                  memory_free: 1062133
                  cpu_idle: 100
                  cpu_wait: 0
                  cpu_us: 0
                  cpu_ks: 0
                  interfaces:
                    interface-1-name:
                      rx_drop: 0
                      tx_drop: 0
                      rate_rx_drop: 0
                      rate_tx_drop: 0
                      bandwidth_ingress_limit_exceeded: 0
                      rate_sent: 3218.53344
                      rate_received: 4875.86672
                      rate_total: 8094.4004
                      pps_limit_exceeded: 0
            text/plain:
              example: |-
                memory_cached{gateway="gateway-1-name"} 211443 1678990460000
                memory_buf{gateway="gateway-1-name"} 29663 1678990460000
                memory_swpd{gateway="gateway-1-name"} 0 1678990460000
                memory_free{gateway="gateway-1-name"} 1010970 1678990460000
                cpu_idle{gateway="gateway-1-name"} 87 1678990460000
                cpu_wait{gateway="gateway-1-name"} 0 1678990460000
                cpu_us{gateway="gateway-1-name"} 8 1678990460000
                cpu_ks{gateway="gateway-1-name"} 5 1678990460000
                rx_drop{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
                tx_drop{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
                rate_rx_drop{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
                rate_tx_drop{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
                bandwidth_ingress_limit_exceeded{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
                rate_sent{gateway="gateway-1-name", interface="interface-1-name"} 6288.8 1678990460000
                rate_received{gateway="gateway-1-name", interface="interface-1-name"} 7771.86672 1678990460000
                rate_total{gateway="gateway-1-name", interface="interface-1-name"} 14060.6664 1678990460000
                pps_limit_exceeded{gateway="gateway-1-name", interface="interface-1-name"} 0 1678990460000
        '403':
          description: Unauthorized                   (4)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key value
security:
  - bearerAuth: []                                    (5)
1 You must provide the IP address or host name of the CoPilot instance you want to access.
2 You can use either Prometheus or JSON schemas.
3 Following are examples of successful results for JSON, followed by Prometheus results.
4 A failed operation with a 403 code indicates unauthorized access due to an incorrect key.
5 You must provide the authorization access key copied from CoPilot.

The specification also lists the metrics supported by the API. A list of all metrics monitored by Aviatrix is available in Metrics Monitored for Aviatrix Resources. The metrics supported by the Network Insights API are also identified in that list.

Status API .yaml Specification

Using the status API, you can determine the status of Aviatrix-managed gateways and tunnels, as well as BGP resources. You can use either JSON or Prometheus schemas.

See the metric OpenAPI .yaml file for an example of the specification.

To generate API output, you must provide the following:

  • IP address or host name of the CoPilot instance you want to access

  • Authorization access key created in and copied from CoPilot

This API provides the following status:

  • Gateways: Up or Down

  • Tunnels: Up or Down

  • BGP: Established or Up

The same success and error codes apply to status and metric APIs:

  • 200 = success

  • 500 = internal server error

  • 403 = unauthorized; incorrect key provided

Testing API Access to a CoPilot Instance

You can verify access to the CoPilot instance from which you want to gather data. Following is an example of how to use the curl command to display output at the command line, in JSON format.

curl -k -X 'GET' \
'https://<copilot_public_ip>/metrics-api/v1/gateways?format=json' \
-H 'Authorization: Bearer <metrics_api_token>'

Output should look similar to the following:

memory_cached{gateway="Controller"} 5375148 1680115793000
memory_buf{gateway="Controller"} 332689 1680115793000
memory_swpd{gateway="Controller"} 0 1680115793000
memory_free{gateway="Controller"} 624738 1680115793000
cpu_idle{gateway="Controller"} 98 1680115793000
cpu_wait{gateway="Controller"} 0 1680115793000