The Avi Load Balancer tracks and maintains metrics data based on several parameters. In some cases, organizations might need additional data unique to their applications or environment. To satisfy this need, user-defined Metrics are provided.

Three new DataScript functions interact with the Avi Load Balancer metrics subsystem to enable organizations to create, manipulate, and access their custom-defined metrics. REST API calls can be used to incorporate the custom data into the customer’s monitoring systems.



A user-defined metric is:

  • An integer and can never be negative.

  • Created and subsequently manipulated by a DataScript running in the SEs upon which the virtual service has been placed.

  • Collected and aggregated by the Controller(s). The Controller can detect anomalies in the values of these metrics.

  • Stored over time so that various metrics system capabilities like averaging, min/max tracking, and summation can be applied.

  • Able to be queried through the Metrics API.

Any given user-defined metric is scoped to the virtual service that creates it through a DataScript. Since a DataScript can be used by more than one virtual service, the Controller has to keep identically named metrics in different virtual services isolated from one another. The interpretation of a user-defined metric is left completely up to the user. Its value is based on conditions detected within the DataScript in which the metric is referenced.

When a metric crosses some user-defined threshold, any number of actions or no action can be triggered within the DataScript.

User-defined Metrics using DataScripts

  1. Use the avi.vs.log() DataScript function to simply report the value of the metric.

  2. Use the avi.vs.rate_limit( type, string_to_limit, [defer_action=False] ) DataScript function to rate-limit the virtual service.

Note:

In most cases, metric data is extracted through calls to the REST API than through DataScripts.

User-defined Metric Types

The Avi Load Balancer supports two types of user-defined metrics:

  • avi.vs.analytics.METRICTYPE_COUNTER: A metric of this type can be incremented or cleared.

  • avi.vs.analytics.METRICTYPE_GAUGE: A metric of this type can be incremented, decremented, cleared, or set.

DataScript Functions for User-defined Metrics

The DataScript functions that manipulate the above metrics are:

  • avi.vs.analytics.counter(metric_name, [operation], [value]): Increments or clears the named counter metric.

  • avi.vs.analytics.gauge(metric_name, [operation], [value]): Increments, decrements, sets or clears the named gauge metric.

  • avi.vs.analytics.get_metric(metric_name, metric_type): Returns the value of the metric, be it of type counter or gauge. Before proceeding, the function first checks if metric_name is defined, then compares the value of metric_type to the type previously stored. If metric_name is not defined, or the type is not correct, the function reports an error on the log, and the request/response causing this function call is canceled.

User-defined Metric Lifecycle

User-defined metrics are always aged and automatically destroyed if not used for more than two hours. Every time a counter or gauge is read or updated, its age is refreshed. Ageing provides automatic garbage collection of user-defined metrics.

Accessing User-defined Metrics

The Avi Load Balancer Controller provides access to these metrics through REST API calls.

In a call such as the following:

api/analytics/metrics/virtualservice/<vs_uuid>?metric_id=user_metrics.sum_counter&obj_id=<obj_id>&step=300&limit=1

obj_id is either the ID of the counter or ‘*’ to identify all the active counter metrics.

Aggregated Values Queried for avi.vs.analytics.METRICTYPE_COUNTER



  • user_metrics.sum_counter: Sum of counter metric values reported over a given period.

For example: The latest 5-minute sample of aggregated user metric having a counter_id equal to Foo can be fetched using following API code:

api/analytics/metrics/virtualservice/<vs_uuid>?metric_id=user.sum_counter&obj_id=Foo&step=300&limit=1

  • user_metrics.avg_counter: The time averaged per-second values of counter metric over a given period.

For example: The latest 5-minute sample of averaged per-second rate of counter metric Foo can be requested using the following API call:

api/analytics/metrics/virtualservice/<vs_uuid>?metric_id=user.avg_counter&obj_id=Foo&step=300&limit=1

  • user_metrics.max_counter and user_metrics.min_counter: Maximum/minimum per-second reported values of counter metric Foo over a given period.

For example: the per-second max and min values can be requested using these API calls:

api/analytics/metrics/virtualservice/<vs_uuid>?metric_id=user.max_counter&obj_id=Foo&step=300&limit=1

api/analytics/metrics/virtualservice/<vs_uuid>?metric_id=user.min_counter&obj_id=Foo&step=300&limit=1

Aggregated Values Queried for avi.vs.analytics.METRICTYPE_GAUGE



  • user_metrics.avg_gauge: Average of raw counter value of type gauge reported over given period.

For example: fetch counter foo through API

/api/analytics/metrics/virtualservice/?metric_id=user_metrics.avg_gauge&limit=1&step=300&obj_id=foo

  • user_metrics,max_gauge: Maximum raw counter value of type gauge reported over given period.

For example: fetch counter ‘foo’ through API.

/api/analytics/metrics/virtualservice/?metric_id=user_metrics.max_gauge&limit=1&step=300&obj_id=foo

  • user_metrics.min_gauge: Minimum raw counter value of type gauge reported over given period.

For example: fetch counter foo through API.

/api/analytics/metrics/virtualservice/?metric_id=user_metrics.min_gauge&limit=1&step=300&obj_id=foo