2 Copyright(c) 2017 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Intel Corporation nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 The Metrics library implements a mechanism by which *producers* can
37 publish numeric information for later querying by *consumers*. In
38 practice producers will typically be other libraries or primary
39 processes, whereas consumers will typically be applications.
41 Metrics themselves are statistics that are not generated by PMDs. Metric
42 information is populated using a push model, where producers update the
43 values contained within the metric library by calling an update function
44 on the relevant metrics. Consumers receive metric information by querying
45 the central metric data, which is held in shared memory.
47 For each metric, a separate value is maintained for each port id, and
48 when publishing metric values the producers need to specify which port is
49 being updated. In addition there is a special id ``RTE_METRICS_GLOBAL``
50 that is intended for global statistics that are not associated with any
51 individual device. Since the metrics library is self-contained, the only
52 restriction on port numbers is that they are less than ``RTE_MAX_ETHPORTS``
53 - there is no requirement for the ports to actually exist.
55 Initialising the library
56 ------------------------
58 Before the library can be used, it has to be initialized by calling
59 ``rte_metrics_init()`` which sets up the metric store in shared memory.
60 This is where producers will publish metric information to, and where
61 consumers will query it from.
65 rte_metrics_init(rte_socket_id());
67 This function **must** be called from a primary process, but otherwise
68 producers and consumers can be in either primary or secondary processes.
73 Metrics must first be *registered*, which is the way producers declare
74 the names of the metrics they will be publishing. Registration can either
75 be done individually, or a set of metrics can be registered as a group.
76 Individual registration is done using ``rte_metrics_reg_name()``:
80 id_1 = rte_metrics_reg_name("mean_bits_in");
81 id_2 = rte_metrics_reg_name("mean_bits_out");
82 id_3 = rte_metrics_reg_name("peak_bits_in");
83 id_4 = rte_metrics_reg_name("peak_bits_out");
85 or alternatively, a set of metrics can be registered together using
86 ``rte_metrics_reg_names()``:
90 const char * const names[] = {
91 "mean_bits_in", "mean_bits_out",
92 "peak_bits_in", "peak_bits_out",
94 id_set = rte_metrics_reg_names(&names[0], 4);
96 If the return value is negative, it means registration failed. Otherwise
97 the return value is the *key* for the metric, which is used when updating
98 values. A table mapping together these key values and the metrics' names
99 can be obtained using ``rte_metrics_get_names()``.
101 Updating metric values
102 ----------------------
104 Once registered, producers can update the metric for a given port using
105 the ``rte_metrics_update_value()`` function. This uses the metric key
106 that is returned when registering the metric, and can also be looked up
107 using ``rte_metrics_get_names()``.
111 rte_metrics_update_value(port_id, id_1, values[0]);
112 rte_metrics_update_value(port_id, id_2, values[1]);
113 rte_metrics_update_value(port_id, id_3, values[2]);
114 rte_metrics_update_value(port_id, id_4, values[3]);
116 if metrics were registered as a single set, they can either be updated
117 individually using ``rte_metrics_update_value()``, or updated together
118 using the ``rte_metrics_update_values()`` function:
122 rte_metrics_update_value(port_id, id_set, values[0]);
123 rte_metrics_update_value(port_id, id_set + 1, values[1]);
124 rte_metrics_update_value(port_id, id_set + 2, values[2]);
125 rte_metrics_update_value(port_id, id_set + 3, values[3]);
127 rte_metrics_update_values(port_id, id_set, values, 4);
129 Note that ``rte_metrics_update_values()`` cannot be used to update
130 metric values from *multiple* *sets*, as there is no guarantee two
131 sets registered one after the other have contiguous id values.
136 Consumers can obtain metric values by querying the metrics library using
137 the ``rte_metrics_get_values()`` function that return an array of
138 ``struct rte_metric_value``. Each entry within this array contains a metric
139 value and its associated key. A key-name mapping can be obtained using the
140 ``rte_metrics_get_names()`` function that returns an array of
141 ``struct rte_metric_name`` that is indexed by the key. The following will
142 print out all metrics for a given port:
146 void print_metrics() {
147 struct rte_metric_value *metrics;
148 struct rte_metric_name *names;
151 len = rte_metrics_get_names(NULL, 0);
153 printf("Cannot get metrics count\n");
157 printf("No metrics to display (none have been registered)\n");
160 metrics = malloc(sizeof(struct rte_metric_value) * len);
161 names = malloc(sizeof(struct rte_metric_name) * len);
162 if (metrics == NULL || names == NULL) {
163 printf("Cannot allocate memory\n");
168 ret = rte_metrics_get_values(port_id, metrics, len);
169 if (ret < 0 || ret > len) {
170 printf("Cannot get metrics values\n");
175 printf("Metrics for port %i:\n", port_id);
176 for (i = 0; i < len; i++)
177 printf(" %s: %"PRIu64"\n",
178 names[metrics[i].key].name, metrics[i].value);
184 Bit-rate statistics library
185 ---------------------------
187 The bit-rate library calculates the exponentially-weighted moving
188 average and peak bit-rates for each active port (i.e. network device).
189 These statistics are reported via the metrics library using the
192 - ``mean_bits_in``: Average inbound bit-rate
193 - ``mean_bits_out``: Average outbound bit-rate
194 - ``ewma_bits_in``: Average inbound bit-rate (EWMA smoothed)
195 - ``ewma_bits_out``: Average outbound bit-rate (EWMA smoothed)
196 - ``peak_bits_in``: Peak inbound bit-rate
197 - ``peak_bits_out``: Peak outbound bit-rate
199 Once initialised and clocked at the appropriate frequency, these
200 statistics can be obtained by querying the metrics library.
205 Before the library can be used, it has to be initialised by calling
206 ``rte_stats_bitrate_create()``, which will return a bit-rate
207 calculation object. Since the bit-rate library uses the metrics library
208 to report the calculated statistics, the bit-rate library then needs to
209 register the calculated statistics with the metrics library. This is
210 done using the helper function ``rte_stats_bitrate_reg()``.
214 struct rte_stats_bitrates *bitrate_data;
216 bitrate_data = rte_stats_bitrate_create();
217 if (bitrate_data == NULL)
218 rte_exit(EXIT_FAILURE, "Could not allocate bit-rate data.\n");
219 rte_stats_bitrate_reg(bitrate_data);
221 Controlling the sampling rate
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224 Since the library works by periodic sampling but does not use an
225 internal thread, the application has to periodically call
226 ``rte_stats_bitrate_calc()``. The frequency at which this function
227 is called should be the intended sampling rate required for the
228 calculated statistics. For instance if per-second statistics are
229 desired, this function should be called once a second.
233 tics_datum = rte_rdtsc();
234 tics_per_1sec = rte_get_timer_hz();
238 tics_current = rte_rdtsc();
239 if (tics_current - tics_datum >= tics_per_1sec) {
240 /* Periodic bitrate calculation */
241 for (idx_port = 0; idx_port < cnt_ports; idx_port++)
242 rte_stats_bitrate_calc(bitrate_data, idx_port);
243 tics_datum = tics_current;
249 Latency statistics library
250 --------------------------
252 The latency statistics library calculates the latency of packet
253 processing by a DPDK application, reporting the minimum, average,
254 and maximum nano-seconds that packet processing takes, as well as
255 the jitter in processing delay. These statistics are then reported
256 via the metrics library using the following names:
258 - ``min_latency_ns``: Minimum processing latency (nano-seconds)
259 - ``avg_latency_ns``: Average processing latency (nano-seconds)
260 - ``mac_latency_ns``: Maximum processing latency (nano-seconds)
261 - ``jitter_ns``: Variance in processing latency (nano-seconds)
263 Once initialised and clocked at the appropriate frequency, these
264 statistics can be obtained by querying the metrics library.
269 Before the library can be used, it has to be initialised by calling
270 ``rte_latencystats_init()``.
274 lcoreid_t latencystats_lcore_id = -1;
276 int ret = rte_latencystats_init(1, NULL);
278 rte_exit(EXIT_FAILURE, "Could not allocate latency data.\n");
281 Triggering statistic updates
282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
284 The ``rte_latencystats_update()`` function needs to be called
285 periodically so that latency statistics can be updated.
289 if (latencystats_lcore_id == rte_lcore_id())
290 rte_latencystats_update();
295 When finished, ``rte_latencystats_uninit()`` needs to be called to
296 de-initialise the latency library.
300 rte_latencystats_uninit();