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