Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Log and Flow Information APIs

In Contrail, log and flow analytics information is collected and stored using a horizontally scalable Contrail collector and NoSQL database. The analytics-api server provides REST APIs to extract this information using queries. The queries use well-known SQL syntax, hiding the underlying complexity of the NoSQL tables.


Use the following GET APIs to identify tables and APIs available for querying.

/analytics/tables -- lists the SQL-type tables available for querying, including the hrefs for each of the tables

/analytics/table/<table> -- lists the APIs available to get information for a given table

/analytics/table/<table>/schema -- lists the schema for a given table


Use the following POST API information to extract data from a table.

/analytics/query -- format your query using the following SQL syntax:

  1. SELECT field1, field2 ...

  2. FROM table1

  3. WHERE field1 = value1 AND field2 = value2 ...

  4. FILTER BY ...

  5. SORT BY ...

  6. LIMIT n

Additionally, it is mandatory to include the start time and the end time for the data range to define the time period for the query data. The parameters of the query are passed through POST data, using the following fields:

  1. start_time — the start of the time period

  2. end_time — the end of the time period

  3. table — the table from which to extract data

  4. select_fields — the columns to display in the extracted data

  5. where — the list of match conditions

POST Data Format Example

The POST data is in JSON format, stored in an idl file. A sample file is displayed in the following.


The result of the query API is also in JSON format.

Query Types

The analytics-api supports two types of queries. Both types use the same POST parameters as described in POST API.

  • sync — Default query mode. The results are sent inline with the query processing.

  • async — To execute a query in async mode, attach the following header to the POST request: Expect: 202-accepted.

Examining Query Status

For an asynchronous query, the analytics-api responds with the code: 202 Accepted. The response contents are a status entity href URL of the form: /analytics/query/<QueryID>. The QueryID is assigned by the analytics-api. To view the response contents, poll the status entity by performing a GET action on the URL. The status entity has a variable named progress, with a number between 0 and 100, representing the approximate percentage completion of the query. When progress is 100, the query processing is complete.

Examining Query Chunks

The status entity has an element named chunks that lists portions (chunks) of query results. Each element of this list has three fields: start_time, end_time, href. The analytics-api determines how many chunks to list to represent the query data. A chunk can include an empty string ("") to indicate that the data query is not yet available. If a partial result is available, the chunk href is of the form: /analytics/query/<QueryID>/chunk-partial/<chunk number>. When the final result of a chunk is available, the href is of the form: /analytics/query/<QueryID>/chunk-final/<chunk number>.

Example Queries for Log and Flow Data

The following example query lists the tables available for query.

The following example query lists details for the table named MessageTable.

The following example query lists the schema for the table named MessageTable.

The following set of example queries explore a message table.