Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Contrail Analytics Application Programming Interfaces (APIs) and User-Visible Entities (UVEs)

 

The Contrail analytics-api server provides a REST API interface to extract the operational state of the Contrail system.

APIs are used by the Contrail Web user interface to present the operational state to users. Other applications might also use the server's REST APIs for analytics or other uses.

This section describes some of the more common APIs and their uses. To see all of the available APIs, navigate the URL tree at the REST interface, starting at the root http://<ip>:<analytics-api-port>. You can also view the Contrail Networking API Reference Guide.

User-Visible Entities

In Contrail, a User-Visible Entity (UVE) is an object entity that might span multiple components in Contrail and might require aggregation before the complete information of the UVE is presented. Examples of UVEs in Contrail are virtual network, virtual machine, vRouter, and similar objects. Complete operational information for a virtual network might span multiple vRouters, config nodes, control nodes, and the like. The analytics-api server aggregates all of this information through REST APIs.

To get information about a UVE, you must have the UVE type and the UVE key. In Contrail, UVEs are identified by type, such as virtual network, virtual machine, vRouter, and so on. A system-wide unique key is associated with each UVE. The key type could be different, based on the UVE type. For example, perhaps a virtual network uses its name as its UVE key, and in the same system, a virtual machine uses its UUID as its key.

The URL /analytics/uves shows the list of all UVE types available in the system.

The following is sample output from /analytics/uves:

Common UVEs in Contrail

This section presents descriptions of some common UVEs in Contrail.

Virtual Network UVE

This UVE provides information associated with a virtual network, such as:

  • list of networks connected to this network

  • list of virtual machines spawned in this network

  • list of access control lists (ACLs) associated with this virtual network

  • global input and output statistics

  • input and output statistics per virtual network pair

The REST API to get a UVE for a specific virtual network is through HTTP GET, using the URL:

/analytics/uves/virtual-network/<key>

The REST API to get UVEs for all virtual machines is through HTTP GET, using the URL:

/analytics/uves/virtual-networks

Virtual Machine UVE

This UVE provides information associated with a virtual machine, such as:

  • list of interfaces in this virtual machine

  • list of floating IPs associated with each interface

  • input and output statistics

The REST API to get a UVE for a specific virtual machine is through HTTP GET, using the URL:

/analytics/uves/virtual-machine/<key>

The REST API to get UVEs for all virtual machines is through HTTP GET, using the URL:

/analytics/uves/virtual-machines

vRouter UVE

This UVE provides information associated with a vRouter, such as:

  • virtual networks present on this vRouter

  • virtual machines spawned on the server of this vRouter

  • statistics of the traffic flowing through this vRouter

The REST API to get a UVE for a specific vRouter is through HTTP GET, using the URL:

/analytics/uves/vrouter/<key>

The REST API to get UVEs for all virtual machines is through HTTP GET, using the URL:

/analytics/uves/vrouters

UVEs for Contrail Nodes

There are multiple node types in Contrail (including the node type vRouter previously described). Other node types include control node, config node, analytics node, and compute node.

There is a UVE for each node type. The common information associated with each node UVE includes:

  • the IP address of the node

  • a list of processes running on the node

  • the CPU and memory utilization of the running processes

Each UVE also has node-specific information, such as:

  • the control node UVE has information about its connectivity to the vRouter and other control nodes

  • the analytics node UVE has information about the number of generators connected

The REST API to get a UVE for a specific config node is through HTTP GET, using the URL:

/analytics/uves/config-node/<key>

The REST API to get UVEs for all config nodes is through HTTP GET, using the URL:

/analytics/uves/config-nodes

Note

Use similar syntax to get UVES for each of the different types of nodes, substituting the node type that you want in place of config-node.

Wild Card Query of UVEs

You can use wildcard queries when you want to get multiple UVEs at the same time. Example queries are the following:

The following HTTP GET with wildcard retrieves all virtual network UVEs:

/analytics/uves/virtual-network/*

The following HTTP GET with wildcard retrieves all virtual network UVEs with name starting with project1:​

/analytics/uves/virtual-network/project1*

Filtering UVE Information

It is possible to retrieve filtered UVE information. The following flags enable you to retrieve partial, filtered information about UVEs.

Supported filter flags include:

  • sfilt : filter by source (usually the hostname of the generator)

  • mfilt : filter by module (the module name of the generator)

  • cfilt : filter by content, useful when only part of a UVE needs to be retrieved

  • kfilt : filter by UVE keys, useful to get multiple, but not all, UVEs of a particular type

Examples

The following HTTP GET with filter retrieves information about virtual network vn1 as provided by the source src1:

/analytics/uves/virtual-network/vn1?sfilt=src1

The following HTTP GET with filter retrieves information about virtual network vn1 as provided by all ApiServer modules:​

​/analytics/uves/virtual-network/vn1?mfilt=ApiServer

Example Output: Virtual Network UVE

Example output for a virtual network UVE:

Example Output: Virtual Machine UVE

Example output for a virtual machine UVE:

Example Output: vRouter UVE

Example output for a vRouter UVE: