doc/guides/prog_guide/telemetry_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4 Telemetry Library
   5 =================
   6
   7 The Telemetry library provides an interface to retrieve information from a
   8 variety of DPDK libraries. The library provides this information via socket
   9 connection, taking requests from a connected client and replying with the JSON
  10 response containing the requested telemetry information.
  11
  12 Telemetry is enabled to run by default when running a DPDK application, and the
  13 telemetry information from enabled libraries is made available. Libraries are
  14 responsible for registering their own commands, and providing the callback
  15 function that will format the library specific stats into the correct data
  16 format, when requested.
  17
  18
  19 Creating Callback Functions
  20 ---------------------------
  21
  22
  23 Function Type
  24 ~~~~~~~~~~~~~
  25
  26 When 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
  33 An 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
  41 For 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
  47 This callback is an example of handling multiple commands in one callback,
  48 and also shows the use of params which holds a port ID. The ``params`` input needs
  49 to be validated and converted to the required integer type for port ID. The ``cmd``
  50 parameter is then used in a comparison to decide which command was requested,
  51 which 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
  77 Formatting Data
  78 ~~~~~~~~~~~~~~~
  79
  80 The callback function provided by the library must format its telemetry
  81 information in the required data format. The Telemetry library provides a data
  82 utilities API to build up the data structure with the required information.
  83 The telemetry library is then responsible for formatting the data structure
  84 into a JSON response before sending to the client.
  85
  86
  87 Array Data
  88 ^^^^^^^^^^
  89
  90 Some data will need to be formatted in a list structure. For example, if a
  91 callback needs to return five integer values in the data response, it can be
  92 constructed 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
 100 The resulting response to the client shows the list data provided above
 101 by 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
 106 Dictionary Data
 107 ^^^^^^^^^^^^^^^
 108
 109 For data that needs to be structured in a dictionary with key/value pairs,
 110 the data utilities API can also be used. For example, some information about
 111 a 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
 121 The resulting response to the client shows the key/value data provided above
 122 by 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
 128 String Data
 129 ^^^^^^^^^^^
 130
 131 Telemetry also supports single string data.
 132 The 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
 138 Giving the following response to the client::
 139
 140     {"/example_lib/string_example": "This is an example string"}
 141
 142 For more information on the range of data functions available in the API,
 143 please refer to the `API doc <https://doc.dpdk.org/api-20.05/rte__telemetry_8h.html>`_
 144
 145
 146 Registering Commands
 147 --------------------
 148
 149 Libraries and applications must register commands to make their information
 150 available via the Telemetry library. This involves providing a string command
 151 in the required format ("/library/command"), the callback function that
 152 will handle formatting the information when required, and help text for the
 153 command. 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
 161 Using Commands
 162 --------------
 163
 164 To use commands, with a DPDK app running (e.g. testpmd), use the
 165 ``dpdk-telemetry.py`` script.
 166 For details on its use, see the :doc:`../howto/telemetry`.