From 98ffdfbcf1ea8f4705fa3dacd6d9ae94d3705733 Mon Sep 17 00:00:00 2001 From: Ciara Power Date: Fri, 24 Jul 2020 12:20:33 +0100 Subject: [PATCH] doc: add more detail to telemetry guides This patch adds examples to the Telemetry HowTo guide, to demonstrate commands that use parameters. The programmer's guide is also modified to include details on writing a callback function for a new command. Signed-off-by: Ciara Power Acked-by: Bruce Richardson --- doc/guides/howto/telemetry.rst | 67 ++++++---- doc/guides/prog_guide/telemetry_lib.rst | 158 ++++++++++++++++++++---- 2 files changed, 171 insertions(+), 54 deletions(-) diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst index b4a34ed674..e7b5434152 100644 --- a/doc/guides/howto/telemetry.rst +++ b/doc/guides/howto/telemetry.rst @@ -29,17 +29,13 @@ Telemetry Initialization The library is enabled by default, however an EAL flag to enable the library exists, to provide backward compatibility for the previous telemetry library -interface. +interface:: -.. code-block:: console + --telemetry - --telemetry +A flag exists to disable Telemetry also:: -A flag exists to disable Telemetry also. - -.. code-block:: console - - --no-telemetry + --no-telemetry Running Telemetry @@ -48,33 +44,50 @@ Running Telemetry The following steps show how to run an application with telemetry support, and query information using the telemetry client python script. -#. Launch testpmd as the primary application with telemetry. - - .. code-block:: console +#. Launch testpmd as the primary application with telemetry:: ./app/dpdk-testpmd -#. Launch the telemetry client script. - - .. code-block:: console +#. Launch the telemetry client script:: python usertools/dpdk-telemetry.py -#. When connected, the script displays the following, waiting for user input. +#. When connected, the script displays the following, waiting for user input:: - .. code-block:: console - - Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2 - {"version": "DPDK 20.05.0-rc0", "pid": 60285, "max_output_len": 16384} - --> + Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2 + {"version": "DPDK 20.05.0-rc2", "pid": 60285, "max_output_len": 16384} + --> #. The user can now input commands to send across the socket, and receive the - response. + response. Some available commands are shown below. + + * List all commands:: + + --> / + {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list", + "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]} + + * Get the list of ethdev ports:: + + --> /ethdev/list + {"/ethdev/list": [0, 1]} + + .. Note:: + + For commands that expect a parameter, use "," to separate the command + and parameter. See examples below. + + * Get extended statistics for an ethdev port:: + + --> /ethdev/xstats,0 + {"/ethdev/xstats": {"rx_good_packets": 0, "tx_good_packets": 0, + "rx_good_bytes": 0, "tx_good_bytes": 0, "rx_missed_errors": 0, + ... + "tx_priority7_xon_to_xoff_packets": 0}} - .. code-block:: console + * Get the help text for a command. This will indicate what parameters are + required. Pass the command as a parameter:: - --> / - {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list", - "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]} - --> /ethdev/list - {"/ethdev/list": [0, 1]} + --> /help,/ethdev/xstats + {"/help": {"/ethdev/xstats": "Returns the extended stats for a port. + Parameters: int port_id"}} diff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst index 8563a7200e..6ea16e9491 100644 --- a/doc/guides/prog_guide/telemetry_lib.rst +++ b/doc/guides/prog_guide/telemetry_lib.rst @@ -16,47 +16,151 @@ function that will format the library specific stats into the correct data format, when requested. -Registering Commands --------------------- +Creating Callback Functions +--------------------------- -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 showing ethdev commands being registered is shown below: + +Function Type +~~~~~~~~~~~~~ + +When creating a callback function in a library/app, it must be of the following type: + +.. code-block:: c + + typedef int (*telemetry_cb)(const char *cmd, const char *params, + struct rte_tel_data *info); + +An example callback function is shown below: + +.. code-block:: c + + 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. .. code-block:: c - rte_telemetry_register_cmd("/ethdev/list", handle_port_list, - "Returns list of available ethdev ports. Takes no parameters"); - rte_telemetry_register_cmd("/ethdev/xstats", handle_port_xstats, - "Returns the extended stats for a port. Parameters: int port_id"); - rte_telemetry_register_cmd("/ethdev/link_status", handle_port_link_status, - "Returns the link status for a port. Parameters: int port_id"); + 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; + } -Formatting JSON response ------------------------- + +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 response. For example, the ethdev library provides a -list of available ethdev ports in a formatted data response, constructed using the -following functions to build up the list: +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. + + +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: .. code-block:: c - rte_tel_data_start_array(d, RTE_TEL_INT_VAL); - RTE_ETH_FOREACH_DEV(port_id) - rte_tel_data_add_array_int(d, port_id); + 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 data structure is then formatted into a JSON response before sending. -The resulting response shows the port list data provided above by the handler -function in ethdev, placed in a JSON reply by telemetry: +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:: -.. code-block:: console + {"/example_lib/five_ints": [0, 1, 2, 3, 4]} - {"/ethdev/list": [0, 1]} + +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: + +.. code-block:: c + + 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}} + + +String Data +^^^^^^^^^^^ + +Telemetry also supports single string data. +The data utilities API can again be used for this, see the example below. + +.. code-block:: c + + 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 docs. +please refer to the `API doc `_ + + +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: + +.. code-block:: c + + rte_telemetry_register_cmd("/example_lib/string_example", handle_string, + "Returns an example string. Takes no parameters"); + + +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 :doc:`../howto/telemetry`. -- 2.20.1