1*24cd1b52SCiara Power.. SPDX-License-Identifier: BSD-3-Clause 2*24cd1b52SCiara Power Copyright(c) 2020 Intel Corporation. 3*24cd1b52SCiara Power 4*24cd1b52SCiara PowerTelemetry Library 5*24cd1b52SCiara Power================= 6*24cd1b52SCiara Power 7*24cd1b52SCiara PowerThe Telemetry library provides an interface to retrieve information from a 8*24cd1b52SCiara Powervariety of DPDK libraries. The library provides this information via socket 9*24cd1b52SCiara Powerconnection, taking requests from a connected client and replying with the JSON 10*24cd1b52SCiara Powerresponse containing the requested telemetry information. 11*24cd1b52SCiara Power 12*24cd1b52SCiara PowerTelemetry is enabled to run by default when running a DPDK application, and the 13*24cd1b52SCiara Powertelemetry information from enabled libraries is made available. Libraries are 14*24cd1b52SCiara Powerresponsible for registering their own commands, and providing the callback 15*24cd1b52SCiara Powerfunction that will format the library specific stats into the correct data 16*24cd1b52SCiara Powerformat, when requested. 17*24cd1b52SCiara Power 18*24cd1b52SCiara Power 19*24cd1b52SCiara PowerRegistering Commands 20*24cd1b52SCiara Power-------------------- 21*24cd1b52SCiara Power 22*24cd1b52SCiara PowerLibraries and applications must register commands to make their information 23*24cd1b52SCiara Poweravailable via the Telemetry library. This involves providing a string command 24*24cd1b52SCiara Powerin the required format ("/library/command"), and the callback function that 25*24cd1b52SCiara Powerwill handle formatting the information when required. An example showing ethdev 26*24cd1b52SCiara Powercommands being registered is shown below: 27*24cd1b52SCiara Power 28*24cd1b52SCiara Power.. code-block:: c 29*24cd1b52SCiara Power 30*24cd1b52SCiara Power rte_telemetry_register_cmd("/ethdev/list", handle_port_list); 31*24cd1b52SCiara Power rte_telemetry_register_cmd("/ethdev/xstats", handle_port_xstats); 32*24cd1b52SCiara Power 33*24cd1b52SCiara Power 34*24cd1b52SCiara PowerFormatting JSON response 35*24cd1b52SCiara Power------------------------ 36*24cd1b52SCiara Power 37*24cd1b52SCiara PowerThe callback function provided by the library must format its telemetry 38*24cd1b52SCiara Powerinformation in the required data format. The Telemetry library provides a data 39*24cd1b52SCiara Powerutilities API to build up the response. For example, the ethdev library provides a 40*24cd1b52SCiara Powerlist of available ethdev ports in a formatted data response, constructed using the 41*24cd1b52SCiara Powerfollowing functions to build up the list: 42*24cd1b52SCiara Power 43*24cd1b52SCiara Power.. code-block:: c 44*24cd1b52SCiara Power 45*24cd1b52SCiara Power rte_tel_data_start_array(d, RTE_TEL_INT_VAL); 46*24cd1b52SCiara Power RTE_ETH_FOREACH_DEV(port_id) 47*24cd1b52SCiara Power rte_tel_data_add_array_int(d, port_id); 48*24cd1b52SCiara Power 49*24cd1b52SCiara PowerThe data structure is then formatted into a JSON response before sending. 50*24cd1b52SCiara PowerThe resulting response shows the port list data provided above by the handler 51*24cd1b52SCiara Powerfunction in ethdev, placed in a JSON reply by telemetry: 52*24cd1b52SCiara Power 53*24cd1b52SCiara Power.. code-block:: console 54*24cd1b52SCiara Power 55*24cd1b52SCiara Power {"/ethdev/list": [0, 1]} 56*24cd1b52SCiara Power 57*24cd1b52SCiara PowerFor more information on the range of data functions available in the API, 58*24cd1b52SCiara Powerplease refer to the docs. 59