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 Registering Commands
  20 --------------------
  21
  22 Libraries and applications must register commands to make their information
  23 available via the Telemetry library. This involves providing a string command
  24 in the required format ("/library/command"), the callback function that
  25 will handle formatting the information when required, and help text for the
  26 command. 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
  38 Formatting JSON response
  39 ------------------------
  40
  41 The callback function provided by the library must format its telemetry
  42 information in the required data format. The Telemetry library provides a data
  43 utilities API to build up the response. For example, the ethdev library provides a
  44 list of available ethdev ports in a formatted data response, constructed using the
  45 following 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
  53 The data structure is then formatted into a JSON response before sending.
  54 The resulting response shows the port list data provided above by the handler
  55 function in ethdev, placed in a JSON reply by telemetry:
  56
  57 .. code-block:: console
  58
  59     {"/ethdev/list": [0, 1]}
  60
  61 For more information on the range of data functions available in the API,
  62 please refer to the docs.