From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5C1C6A0518; Fri, 24 Jul 2020 13:26:17 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id D604E1C010; Fri, 24 Jul 2020 13:26:15 +0200 (CEST) Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 4EE651BFE7 for ; Fri, 24 Jul 2020 13:26:13 +0200 (CEST) IronPort-SDR: +r4WAP3Ye/UUI1BOUh6o6cbvjBgw8feMwNHHscN/46R2KyxfG1rwzWJ95Pjsykv9QAk7eviS3V KI3u0/8+X/9A== X-IronPort-AV: E=McAfee;i="6000,8403,9691"; a="148607319" X-IronPort-AV: E=Sophos;i="5.75,390,1589266800"; d="scan'208";a="148607319" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga102.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Jul 2020 04:26:12 -0700 IronPort-SDR: WFDCjUhSLiV+XEyye+rPhFeC69qeSEAzDi25JoUU+p7yO5mvCXa1JobLevx2LUQXe7N7Sb3RKc 457i7IeowS/Q== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.75,390,1589266800"; d="scan'208";a="488708627" Received: from silpixa00399953.ir.intel.com (HELO silpixa00399953.ger.corp.intel.com) ([10.237.222.53]) by fmsmga006.fm.intel.com with ESMTP; 24 Jul 2020 04:26:10 -0700 From: Ciara Power To: kevin.laatz@intel.com Cc: dev@dpdk.org, bruce.richardson@intel.com, thomas@monjalon.net, Ciara Power Date: Fri, 24 Jul 2020 12:20:33 +0100 Message-Id: <20200724112033.24860-1-ciara.power@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200721160924.62082-1-ciara.power@intel.com> References: <20200721160924.62082-1-ciara.power@intel.com> Subject: [dpdk-dev] [PATCH v3] doc: add more detail to telemetry guides X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 --- v3: - Replaced direct code examples with generic examples. - Replaced ref label with :doc: syntax to link guides. - Replaced console code-block label with :: on previous lines. - Added links to API doc. - Modified some formatting. v2: - Replaced examples of using commands in the programmer's guide with a link to the HowTo guide. - Added an example showing the use of a single string value. - Replaced inline functions with a synthetic example function below the list of parameters. --- doc/guides/howto/telemetry.rst | 67 ++++++---- doc/guides/prog_guide/telemetry_lib.rst | 160 +++++++++++++++++++----- 2 files changed, 172 insertions(+), 55 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..c01e2480ce 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 - 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"); + 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) -Formatting JSON response ------------------------- +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 + + 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 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. -.. 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); +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); + 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:: -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: + {"/example_lib/five_ints": [0, 1, 2, 3, 4]} -.. code-block:: console - {"/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.17.1