End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

View Traffic Metrics

How to view the traffic metrics gathered by NGINX Controller Analytics.

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:

• Environment
• Gateway
• App and Component

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"