View Traffic Metrics

Overview

This topic explains how to use the NGINX Controller REST API to view traffic metrics.

See Also:
Refer to Overview: Traffic Metrics to learn how NGINX Controller collects, aggregates, and reports traffic metrics.

Before You Begin

To view traffic metrics, first confirm that you’ve correctly configured NGINX Controller.

The following resources should have the status Configured:

Initially, the graphs will display No data yet, and querying the Metrics API for traffic metrics will result in an empty response. As soon as the Component starts to receive traffic, the traffic-related data will be displayed in the graphs and the Dashboards in the NGINX Controller user interface and will be returned in API responses.

Note:
If traffic stops flowing to a resource (for example, an Application or Component), then no traffic metrics will be available for the resource.

View Traffic Metrics Using the REST API

  • To view the full list of metrics and dimensions, send a GET request to the /analytics/catalogs/metrics endpoint:

    curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/catalogs/metrics"
    
  • To view a detailed description for a metric, send a GET request to the /analytics/catalogs/metrics/{metricName} endpoint:

    curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/catalogs/metrics/client.latency.total"
    
  • Likewise, to view the full list of available dimensions, send a GET request to the /analytics/catalogs/dimensions endpoint:

    curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/catalogs/dimensions"
    
See Also:
Refer to the Catalogs Reference for information about all of the dimensions and metrics collected by NGINX Controller.

Example REST API Queries for Traffic Metrics

Because traffic metrics are already aggregated, you should be careful about using the Metrics API for aggregations.

Example 1

Goal: Retrieve the total number of requests for the last 3 hours:

curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=SUM(http.request.count)&startTime=now-3h"

The Metrics API returns a single value per dimension set. That value is the sum of the aggregated values (in 30s intervals) for the last 3 hours.

Example 2

Goal: Retrieve an average value of max client latencies for my app – let’s call it app1 – for the last day:

curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=AVG(client.latency.max)&startTime=now-24h&filter=app='app1'"

Example 3

Important:
Because traffic metrics are pre-aggregated, using AVG aggregation with these metrics isn’t recommended.

Imagine you have one application configured with one URI (recorded in the http.uri dimension of each traffic-related metric). In the last 30 seconds, a user queried that URI 5 times. The client.request.latency values for each request were: 1 ms, 2 ms, 3 ms, 4 ms, 5 ms.

The final metric values returned by the Metrics API will be:

  • client.request.latency.total = 15 ms
  • client.request.latency.count = 5

The following query returns the average client.request.latency.total = 15, as you have one aggregated sample with value 15.

curl -X GET --cookie "session=<session cookie>" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=AVG(client.request.latency.total)&startTime=now-24h"

This documentation applies to the following versions of NGINX Controller Documentation: 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15 and 3.16.