58. Telemetry Library

The Telemetry library provides an interface to retrieve information from a variety of DPDK libraries. The library provides this information via socket connection, taking requests from a connected client and replying with the JSON response containing the requested telemetry information.

Telemetry is enabled to run by default when running a DPDK application, and the telemetry information from enabled libraries is made available. Libraries are responsible for registering their own commands, and providing the callback function that will format the library specific stats into the correct data format, when requested.

58.1. Creating Callback Functions

58.1.1. Function Type

When creating a callback function in a library/app, it must be of the following type:

typedef int (*telemetry_cb)(const char *cmd, const char *params,
        struct rte_tel_data *info);

An example callback function is shown below:

static int
handle_example_cmd(const char *cmd __rte_unused, const char *params __rte_unused,
        struct rte_tel_data *d)

For more detail on the callback function parameters, please refer to the definition in the API doc

Example Callback

This callback is an example of handling multiple commands in one callback, and also shows the use of params which holds a port ID. The params input needs to be validated and converted to the required integer type for port ID. The cmd parameter is then used in a comparison to decide which command was requested, which will decide what port information should fill the rte_tel_data structure.

int
handle_cmd_request(const char *cmd, const char *params,
      struct rte_tel_data *d)
{
   int port_id, used = 0;

   if (params == NULL || strlen(params) == 0 || !isdigit(*params))
      return -1;

   port_id = atoi(params);
   if (!rte_eth_dev_is_valid_port(port_id))
      return -1;

   if (strcmp(cmd, "/cmd_1") == 0)
      /* Build up port data requested for command 1 */
   else
      /* Build up port data requested for command 2 */

    return used;
}

58.1.2. Formatting Data

The callback function provided by the library must format its telemetry information in the required data format. The Telemetry library provides a data utilities API to build up the data structure with the required information. The telemetry library is then responsible for formatting the data structure into a JSON response before sending to the client.

58.1.2.1. Array Data

Some data will need to be formatted in a list structure. For example, if a callback needs to return five integer values in the data response, it can be constructed using the following functions to build up the list:

rte_tel_data_start_array(d, RTE_TEL_INT_VAL);
    for(i = 0; i < 5; i++)
        rte_tel_data_add_array_int(d, i);

The resulting response to the client shows the list data provided above by the handler function in the library/app, placed in a JSON reply by telemetry:

{"/example_lib/five_ints": [0, 1, 2, 3, 4]}

58.1.2.2. Dictionary Data

For data that needs to be structured in a dictionary with key/value pairs, the data utilities API can also be used. For example, some information about a brownie recipe is constructed in the callback function shown below:

rte_tel_data_start_dict(d);
rte_tel_data_add_dict_string(d, "Recipe", "Brownies");
rte_tel_data_add_dict_int(d, "Prep time (mins)", 25);
rte_tel_data_add_dict_int(d, "Cooking time (mins)", 30);
rte_tel_data_add_dict_int(d, "Serves", 16);

The resulting response to the client shows the key/value data provided above by the handler function in telemetry, placed in a JSON reply by telemetry:

{"/example_lib/brownie_recipe": {"Recipe": "Brownies", "Prep time (mins)": 25,
  "Cooking time (mins)": 30, "Serves": 16}}

58.1.2.3. String Data

Telemetry also supports single string data. The data utilities API can again be used for this, see the example below.

rte_tel_data_string(d, "This is an example string");

Giving the following response to the client:

{"/example_lib/string_example": "This is an example string"}

For more information on the range of data functions available in the API, please refer to the API doc

58.2. Registering Commands

Libraries and applications must register commands to make their information available via the Telemetry library. This involves providing a string command in the required format (“/library/command”), the callback function that will handle formatting the information when required, and help text for the command. An example command being registered is shown below:

rte_telemetry_register_cmd("/example_lib/string_example", handle_string,
        "Returns an example string. Takes no parameters");

58.3. Using Commands

To use commands, with a DPDK app running (e.g. testpmd), use the dpdk-telemetry.py script. For details on its use, see the DPDK Telemetry User Guide.