.. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Intel Corporation. .. _Metrics_Library: Metrics Library =============== The Metrics library implements a mechanism by which *producers* can publish numeric information for later querying by *consumers*. In practice producers will typically be other libraries or primary processes, whereas consumers will typically be applications. Metrics themselves are statistics that are not generated by PMDs. Metric information is populated using a push model, where producers update the values contained within the metric library by calling an update function on the relevant metrics. Consumers receive metric information by querying the central metric data, which is held in shared memory. For each metric, a separate value is maintained for each port id, and when publishing metric values the producers need to specify which port is being updated. In addition there is a special id ``RTE_METRICS_GLOBAL`` that is intended for global statistics that are not associated with any individual device. Since the metrics library is self-contained, the only restriction on port numbers is that they are less than ``RTE_MAX_ETHPORTS`` - there is no requirement for the ports to actually exist. Initializing 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. .. code-block:: c 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. 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()``: .. code-block:: c 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()``: .. code-block:: c 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()``. 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()``. .. code-block:: c 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: .. code-block:: c 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. 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: .. code-block:: c 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); } Deinitialising the library -------------------------- Once the library usage is done, it must be deinitialized by calling ``rte_metrics_deinit()`` which will free the shared memory reserved during initialization. .. code-block:: c err = rte_metrics_deinit(void); If the return value is negative, it means deinitialization failed. This function **must** be called from a primary process. 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. Initialization ~~~~~~~~~~~~~~ Before the library can be used, it has to be initialised by calling ``rte_stats_bitrate_create()``, which will return a bit-rate calculation object. Since the bit-rate library uses the metrics library to report the calculated statistics, the bit-rate library then needs to register the calculated statistics with the metrics library. This is done using the helper function ``rte_stats_bitrate_reg()``. .. code-block:: c 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); Controlling the sampling rate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since the library works by periodic sampling but does not use an internal thread, the application has to periodically call ``rte_stats_bitrate_calc()``. The frequency at which this function is called should be the intended sampling rate required for the calculated statistics. For instance if per-second statistics are desired, this function should be called once a second. .. code-block:: c 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; } /* ... */ } 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. Initialization ~~~~~~~~~~~~~~ Before the library can be used, it has to be initialised by calling ``rte_latencystats_init()``. .. code-block:: c 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"); Triggering statistic updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``rte_latencystats_update()`` function needs to be called periodically so that latency statistics can be updated. .. code-block:: c if (latencystats_lcore_id == rte_lcore_id()) rte_latencystats_update(); Library shutdown ~~~~~~~~~~~~~~~~ When finished, ``rte_latencystats_uninit()`` needs to be called to de-initialise the latency library. .. code-block:: c rte_latencystats_uninit(); Timestamp and latency calculation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Latency stats library marks the time in the timestamp field of the mbuf for the ingress packets and sets the ``RTE_MBUF_F_RX_TIMESTAMP`` flag of ``ol_flags`` for the mbuf to indicate the marked time as a valid one. At the egress, the mbufs with the flag set are considered having valid timestamp and are used for the latency calculation.