40. Metrics Library

40.1. Initialising the library

Before the library can be used, it has to be initialized by calling rte_metrics_init() which sets up the metric store in shared memory. This is where producers will publish metric information to, and where consumers will query it from.

rte_metrics_init(rte_socket_id());

This function must be called from a primary process, but otherwise producers and consumers can be in either primary or secondary processes.

40.2. Registering metrics

Metrics must first be registered, which is the way producers declare the names of the metrics they will be publishing. Registration can either be done individually, or a set of metrics can be registered as a group. Individual registration is done using rte_metrics_reg_name():

id_1 = rte_metrics_reg_name("mean_bits_in");
id_2 = rte_metrics_reg_name("mean_bits_out");
id_3 = rte_metrics_reg_name("peak_bits_in");
id_4 = rte_metrics_reg_name("peak_bits_out");

or alternatively, a set of metrics can be registered together using rte_metrics_reg_names():

const char * const names[] = {
    "mean_bits_in", "mean_bits_out",
    "peak_bits_in", "peak_bits_out",
};
id_set = rte_metrics_reg_names(&names[0], 4);

If the return value is negative, it means registration failed. Otherwise the return value is the key for the metric, which is used when updating values. A table mapping together these key values and the metrics’ names can be obtained using rte_metrics_get_names().

40.3. Updating metric values

Once registered, producers can update the metric for a given port using the rte_metrics_update_value() function. This uses the metric key that is returned when registering the metric, and can also be looked up using rte_metrics_get_names().

rte_metrics_update_value(port_id, id_1, values[0]);
rte_metrics_update_value(port_id, id_2, values[1]);
rte_metrics_update_value(port_id, id_3, values[2]);
rte_metrics_update_value(port_id, id_4, values[3]);

if metrics were registered as a single set, they can either be updated individually using rte_metrics_update_value(), or updated together using the rte_metrics_update_values() function:

rte_metrics_update_value(port_id, id_set, values[0]);
rte_metrics_update_value(port_id, id_set + 1, values[1]);
rte_metrics_update_value(port_id, id_set + 2, values[2]);
rte_metrics_update_value(port_id, id_set + 3, values[3]);

rte_metrics_update_values(port_id, id_set, values, 4);

Note that rte_metrics_update_values() cannot be used to update metric values from multiple sets, as there is no guarantee two sets registered one after the other have contiguous id values.

40.4. Querying metrics

Consumers can obtain metric values by querying the metrics library using the rte_metrics_get_values() function that return an array of struct rte_metric_value. Each entry within this array contains a metric value and its associated key. A key-name mapping can be obtained using the rte_metrics_get_names() function that returns an array of struct rte_metric_name that is indexed by the key. The following will print out all metrics for a given port:

void print_metrics() {
    struct rte_metric_value *metrics;
    struct rte_metric_name *names;
    int len;

    len = rte_metrics_get_names(NULL, 0);
    if (len < 0) {
        printf("Cannot get metrics count\n");
        return;
    }
    if (len == 0) {
        printf("No metrics to display (none have been registered)\n");
        return;
    }
    metrics = malloc(sizeof(struct rte_metric_value) * len);
    names =  malloc(sizeof(struct rte_metric_name) * len);
    if (metrics == NULL || names == NULL) {
        printf("Cannot allocate memory\n");
        free(metrics);
        free(names);
        return;
    }
    ret = rte_metrics_get_values(port_id, metrics, len);
    if (ret < 0 || ret > len) {
        printf("Cannot get metrics values\n");
        free(metrics);
        free(names);
        return;
    }
    printf("Metrics for port %i:\n", port_id);
    for (i = 0; i < len; i++)
        printf("  %s: %"PRIu64"\n",
            names[metrics[i].key].name, metrics[i].value);
    free(metrics);
    free(names);
}

40.5. Bit-rate statistics library

The bit-rate library calculates the exponentially-weighted moving average and peak bit-rates for each active port (i.e. network device). These statistics are reported via the metrics library using the following names:

• mean_bits_in: Average inbound bit-rate
• mean_bits_out: Average outbound bit-rate
• ewma_bits_in: Average inbound bit-rate (EWMA smoothed)
• ewma_bits_out: Average outbound bit-rate (EWMA smoothed)
• peak_bits_in: Peak inbound bit-rate
• peak_bits_out: Peak outbound bit-rate

Once initialised and clocked at the appropriate frequency, these statistics can be obtained by querying the metrics library.

struct rte_stats_bitrates *bitrate_data;

bitrate_data = rte_stats_bitrate_create();
if (bitrate_data == NULL)
    rte_exit(EXIT_FAILURE, "Could not allocate bit-rate data.\n");
rte_stats_bitrate_reg(bitrate_data);

tics_datum = rte_rdtsc();
tics_per_1sec = rte_get_timer_hz();

while( 1 ) {
    /* ... */
    tics_current = rte_rdtsc();
    if (tics_current - tics_datum >= tics_per_1sec) {
        /* Periodic bitrate calculation */
        for (idx_port = 0; idx_port < cnt_ports; idx_port++)
                rte_stats_bitrate_calc(bitrate_data, idx_port);
            tics_datum = tics_current;
        }
    /* ... */
}

40.6. Latency statistics library

The latency statistics library calculates the latency of packet processing by a DPDK application, reporting the minimum, average, and maximum nano-seconds that packet processing takes, as well as the jitter in processing delay. These statistics are then reported via the metrics library using the following names:

• min_latency_ns: Minimum processing latency (nano-seconds)
• avg_latency_ns: Average processing latency (nano-seconds)
• mac_latency_ns: Maximum processing latency (nano-seconds)
• jitter_ns: Variance in processing latency (nano-seconds)

Once initialised and clocked at the appropriate frequency, these statistics can be obtained by querying the metrics library.

lcoreid_t latencystats_lcore_id = -1;

int ret = rte_latencystats_init(1, NULL);
if (ret)
    rte_exit(EXIT_FAILURE, "Could not allocate latency data.\n");

if (latencystats_lcore_id == rte_lcore_id())
    rte_latencystats_update();

rte_latencystats_uninit();