Prerequisites 

Please consider reading The Tech Insights Monitoring Query API before proceeding

Please ensure that you have read How Do I Authenticate to use the Query Service API? and The Tech Insights Monitoring Query API - Information Queries before continuing with this section.

Introduction

In contrast to the Tech Insights/M API queries, all metrics are obtained by POSTing the request to a single endpoint. The nature of the metric being requested is determined by parameters sent to  https://api.vyopta.com/cpmm/api/v1/orgs/{orgId}/metrics

In further contrast, all parameters are sent in a JSON request body, with content type of application/json.

There are two types of metrics available - KPI, which returns a single value, and trend, which returns time-series data downsampled appropriately for the duration requested. 

Metrics calls are authenticated in the same manner as all other API calls. Please see How Do I Authenticate to use the Query Service API? for more information, or consult the Postman examples. 

Device Filters

Metrics can be filtered on  device type - a list of valid device types (bridges, call controls and endpoints) can be obtained by performing a GET against https://api.vyopta.com/cpmm/api/v1/orgs/{orgId}/metrics/models

with the results being returned in JSON array.

Please see Postman example Models in the Metrics folder.

Available Metrics

The list of available metrics can be obtained by performing a GET against

https://api.vyopta.com/cpmm/api/v1/orgs/{orgId}/metrics/names

the results are also returned in a JSON array

Please see Postman example Names in the Metrics folder.

Metric Types

KPI

The KPI metric type returns a single value, and are requested by setting the query parameter of resultType to the value of kpi.

The value returned will be the value associated with the last timestamped data in the window specified by query parameters start and end

The metrics that can be requested are those returned by the Names request, above, and are specified using the name parameter. 

Trend

Trend data is returned as time-series data in a JSON array - this data may be used to feed into any up-stream processing system of your choice. 

Trend data is requested by setting the query parameter of resultType to the value of kpi.

The value returned will be the value associated with the last timestamped data in the window specified by query parameters start and end

The metrics that can be requested are those returned by the Names request, above, and are specified using the name parameter. 

Results may be grouped using the group_by parameter

Refining the Request

Filtering 

Requests can contain a filter in the query parameter of the JSON body. Filters are constructed in the same way as for the API query calls, although care to correctly escape quotation characters etc (using a back-slash) should be taken, as per JSON syntax requirements.

The items available for filtering differ by device types

For Endpoints

• deleted
• endpoint_id
• firmware
• manufacturer 
• model
• name
• endpoint_tag

For System devices

• deleted
• manufacturer
• name
• system_id
• type

For example: "query" : "tags==\"system_id=1*\" or tags==\"system_id=3\" or tags==\"type=RMX\""

Grouping

Items may be grouped using the group_by parameter, which takes a comma-separated list of the following 

• *
• deleted
• endpoint_id
• firmware
• model
• name
• endpoint_tag
• manufacturer
• name
• system_id
• type

For example: "group_by" : "type"

Aggregation

The returned values will be determined by the aggregation function used - 

• latest - the first value. Use with care since this is often not the wanted grouping 
• min - the minimum value over the selected time frame
• max - the maximum value over the selected time frame
• average - the mean value over the selected time frame
• sum - the arithmetic sum of the values.
• unknown

The use of the 'latest' aggregation function will return the first matching data - this should be used with caution since it is often not the data expected.

Down Sampling 

The data returned as time-series data may be down-sampled depending upon the time window selected. The range of down-sampling is from 10 minutes to 12 hours (10, 60, or 720 minutes). Should higher precision data be required then the query window should be reduced. 

Examples 

The following Postman examples are provided:

• Names - get metric names
• Models - get model entities that can be used to construct filters
• Endpoints Available KPI - return the value of the endpoint.status.available metric
• Endpoints Available Trend - return a time-series of endpoint.status.available values
• Calls Min KPI - minimum calls present over time window
• Calls Max KPI - maximum calls present over time window
• Calls Trend - time-series data for call count over time window.

The examples are attached to The Tech Insights Monitoring Query API - Information Queries, which should be read before using the above.