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 19Creating Callback Functions 20--------------------------- 21 22 23Function Type 24~~~~~~~~~~~~~ 25 26When creating a callback function in a library/app, it must be of the following type: 27 28.. code-block:: c 29 30 typedef int (*telemetry_cb)(const char *cmd, const char *params, 31 struct rte_tel_data *info); 32 33An example callback function is shown below: 34 35.. code-block:: c 36 37 static int 38 handle_example_cmd(const char *cmd __rte_unused, const char *params __rte_unused, 39 struct rte_tel_data *d) 40 41For more detail on the callback function parameters, please refer to the 42`definition in the API doc 43<https://doc.dpdk.org/api/rte__telemetry_8h.html#a41dc74d561442bb6184ee6dd1f9b5bcc>`_ 44 45**Example Callback** 46 47This callback is an example of handling multiple commands in one callback, 48and also shows the use of params which holds a port ID. The ``params`` input needs 49to be validated and converted to the required integer type for port ID. The ``cmd`` 50parameter is then used in a comparison to decide which command was requested, 51which will decide what port information should fill the ``rte_tel_data`` structure. 52 53.. code-block:: c 54 55 int 56 handle_cmd_request(const char *cmd, const char *params, 57 struct rte_tel_data *d) 58 { 59 int port_id, used = 0; 60 61 if (params == NULL || strlen(params) == 0 || !isdigit(*params)) 62 return -1; 63 64 port_id = atoi(params); 65 if (!rte_eth_dev_is_valid_port(port_id)) 66 return -1; 67 68 if (strcmp(cmd, "/cmd_1") == 0) 69 /* Build up port data requested for command 1 */ 70 else 71 /* Build up port data requested for command 2 */ 72 73 return used; 74 } 75 76 77Formatting Data 78~~~~~~~~~~~~~~~ 79 80The callback function provided by the library must format its telemetry 81information in the required data format. The Telemetry library provides a data 82utilities API to build up the data structure with the required information. 83The telemetry library is then responsible for formatting the data structure 84into a JSON response before sending to the client. 85 86 87Array Data 88^^^^^^^^^^ 89 90Some data will need to be formatted in a list structure. For example, if a 91callback needs to return five integer values in the data response, it can be 92constructed using the following functions to build up the list: 93 94.. code-block:: c 95 96 rte_tel_data_start_array(d, RTE_TEL_INT_VAL); 97 for(i = 0; i < 5; i++) 98 rte_tel_data_add_array_int(d, i); 99 100The resulting response to the client shows the list data provided above 101by the handler function in the library/app, placed in a JSON reply by telemetry:: 102 103 {"/example_lib/five_ints": [0, 1, 2, 3, 4]} 104 105 106Dictionary Data 107^^^^^^^^^^^^^^^ 108 109For data that needs to be structured in a dictionary with key/value pairs, 110the data utilities API can also be used. For example, some information about 111a brownie recipe is constructed in the callback function shown below: 112 113.. code-block:: c 114 115 rte_tel_data_start_dict(d); 116 rte_tel_data_add_dict_string(d, "Recipe", "Brownies"); 117 rte_tel_data_add_dict_int(d, "Prep time (mins)", 25); 118 rte_tel_data_add_dict_int(d, "Cooking time (mins)", 30); 119 rte_tel_data_add_dict_int(d, "Serves", 16); 120 121The resulting response to the client shows the key/value data provided above 122by the handler function in telemetry, placed in a JSON reply by telemetry:: 123 124 {"/example_lib/brownie_recipe": {"Recipe": "Brownies", "Prep time (mins)": 25, 125 "Cooking time (mins)": 30, "Serves": 16}} 126 127 128String Data 129^^^^^^^^^^^ 130 131Telemetry also supports single string data. 132The data utilities API can again be used for this, see the example below. 133 134.. code-block:: c 135 136 rte_tel_data_string(d, "This is an example string"); 137 138Giving the following response to the client:: 139 140 {"/example_lib/string_example": "This is an example string"} 141 142For more information on the range of data functions available in the API, 143please refer to the `API doc <https://doc.dpdk.org/api/rte__telemetry_8h.html>`_ 144 145 146Registering Commands 147-------------------- 148 149Libraries and applications must register commands to make their information 150available via the Telemetry library. This involves providing a string command 151in the required format ("/library/command"), the callback function that 152will handle formatting the information when required, and help text for the 153command. An example command being registered is shown below: 154 155.. code-block:: c 156 157 rte_telemetry_register_cmd("/example_lib/string_example", handle_string, 158 "Returns an example string. Takes no parameters"); 159 160 161Using Commands 162-------------- 163 164To use commands, with a DPDK app running (e.g. testpmd), use the 165``dpdk-telemetry.py`` script. 166For details on its use, see the :doc:`../howto/telemetry`. 167