[dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides

[dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides

[Ciara Power]

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 <ciara.power@intel.com>

---
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          |  46 ++++++-
 doc/guides/prog_guide/telemetry_lib.rst | 172 ++++++++++++++++++++----
 2 files changed, 187 insertions(+), 31 deletions(-)

diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst
index b4a34ed67..7e8a5d6f3 100644
--- a/doc/guides/howto/telemetry.rst
+++ b/doc/guides/howto/telemetry.rst
@@ -1,6 +1,7 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2020 Intel Corporation.
 
+.. _telemetry:
 
 DPDK Telemetry User Guide
 =========================
@@ -69,12 +70,43 @@ and query information using the telemetry client python script.
       -->
 
 #. The user can now input commands to send across the socket, and receive the
-   response.
+   response. Some available commands are shown below.
 
-   .. code-block:: console
+   * List all commands.
+
+      .. code-block:: console
+
+         --> /
+         {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list",
+         "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]}
+
+   * Get the list of ethdev ports.
+
+      .. code-block:: console
+
+         --> /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.
+
+      .. code-block:: console
+
+         --> /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}}
+
+   * Get the help text for a command. This will indicate what parameters are
+     required. Pass the command as a parameter.
+
+      .. code-block:: console
 
-      --> /
-      {"/": ["/", "/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 8563a7200..694cef26b 100644
--- a/doc/guides/prog_guide/telemetry_lib.rst
+++ b/doc/guides/prog_guide/telemetry_lib.rst
@@ -16,6 +16,150 @@ function that will format the library specific stats into the correct data
 format, when requested.
 
 
+Creating Callback Functions
+---------------------------
+
+
+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);
+
+For example, the callback for "/ethdev/list" is:
+
+.. code-block:: c
+
+    static int
+    handle_port_list(const char *cmd __rte_unused, const char *params __rte_unused,
+            struct rte_tel_data *d)
+
+The parameters for a callback function are:
+
+* **cmd**
+
+  This is the command requested by the client, e.g. "/ethdev/list".
+  For most callbacks this may be unused, however it will allow for handling
+  multiple commands in one callback function. This can be seen in the example
+  callback below.
+
+* **params**
+
+  This will contain any parameters required for the command. For example
+  when calling "/ethdev/link_status,0", the port ID will be passed to the
+  callback function in params. This can be seen in the example callback below.
+
+* **d**
+
+  The rte_tel_data pointer will be used by the callback function to format the
+  requested data to be returned to Telemetry. The data APIs provided will
+  enable adding to the struct, examples of this are shown later in this
+  document.
+
+**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 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, 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:
+
+  .. 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);
+
+  The resulting response to the client shows the port list data provided above
+  by the handler function in ethdev, placed in a JSON reply by telemetry:
+
+  .. 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, telemetry provides an
+  info command that has multiple key/value pairs, constructed in the callback
+  function shown below:
+
+  .. code-block:: c
+
+     rte_tel_data_start_dict(d);
+     rte_tel_data_add_dict_string(d, "version", rte_version());
+     rte_tel_data_add_dict_int(d, "pid", getpid());
+     rte_tel_data_add_dict_int(d, "max_output_len", MAX_OUTPUT_LEN);
+
+  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:
+
+  .. code-block:: console
+
+     {"/info": {"version": "DPDK 20.08.0-rc0", "pid": 3838, "max_output_len": 16384}}
+
+* **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:
+
+  .. code-block:: console
+
+     {"/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.
+
+
 Registering Commands
 --------------------
 
@@ -35,28 +179,8 @@ command. An example showing ethdev commands being registered is shown below:
             "Returns the link status for a port. Parameters: int port_id");
 
 
-Formatting JSON response
-------------------------
-
-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:
+Using Commands
+--------------
 
-.. 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);
-
-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:
-
-.. code-block:: console
-
-    {"/ethdev/list": [0, 1]}
-
-For more information on the range of data functions available in the API,
-please refer to the docs.
+To use commands, with a DPDK app running (e.g. testpmd), use the
+dpdk-telemetry.py script. For details on its use, see the :ref:`telemetry`.
-- 
2.17.1

Re: [dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides

[Bruce Richardson]

On Tue, Jul 21, 2020 at 05:09:24PM +0100, Ciara Power wrote:
> 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 <ciara.power@intel.com>
> 
> ---
> 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          |  46 ++++++-
>  doc/guides/prog_guide/telemetry_lib.rst | 172 ++++++++++++++++++++----
>  2 files changed, 187 insertions(+), 31 deletions(-)
> 
Missed threading patch with v1, but content looks fine to me.

Acked-by: Bruce Richardson <bruce.richardson@intel.com>

Re: [dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides

[Thomas Monjalon]

21/07/2020 18:09, Ciara Power:
> --- a/doc/guides/howto/telemetry.rst
> +++ b/doc/guides/howto/telemetry.rst
> @@ -1,6 +1,7 @@
>  ..  SPDX-License-Identifier: BSD-3-Clause
>      Copyright(c) 2020 Intel Corporation.
>  
> +.. _telemetry:

We don't need such anchor.
The beginning of a page can be linked via :doc: syntax.
Note: I would support a patch removing all such existing anchors
at beginning of files.

[...]
> +   * List all commands.
> +
> +      .. code-block:: console

I think you can achieve the same result as code-block
with adding double colons (::) at the end of the previous line:
	* List all commands::

[...]
> --- a/doc/guides/prog_guide/telemetry_lib.rst
> +++ b/doc/guides/prog_guide/telemetry_lib.rst
> +The parameters for a callback function are:
> +
> +* **cmd**
> +
> +  This is the command requested by the client, e.g. "/ethdev/list".
> +  For most callbacks this may be unused, however it will allow for handling
> +  multiple commands in one callback function. This can be seen in the example
> +  callback below.
> +
> +* **params**
> +
> +  This will contain any parameters required for the command. For example
> +  when calling "/ethdev/link_status,0", the port ID will be passed to the
> +  callback function in params. This can be seen in the example callback below.
> +
> +* **d**
> +
> +  The rte_tel_data pointer will be used by the callback function to format the
> +  requested data to be returned to Telemetry. The data APIs provided will
> +  enable adding to the struct, examples of this are shown later in this
> +  document.

It looks like a doxygen-level comment.
Why not linking doxygen from here and focus on example in this guide?
Note that we can also link example code from doxygen.

> +
> +**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 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**

It looks like a sub-title.
Please prefer sub-titles because they appear in the menu
and can be referenced with a direct HTML link.


[...]
> +  .. code-block:: c
> +
> +     rte_tel_data_start_dict(d);
> +     rte_tel_data_add_dict_string(d, "version", rte_version());
> +     rte_tel_data_add_dict_int(d, "pid", getpid());
> +     rte_tel_data_add_dict_int(d, "max_output_len", MAX_OUTPUT_LEN);
> +
> +  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:
> +
> +  .. code-block:: console
> +
> +     {"/info": {"version": "DPDK 20.08.0-rc0", "pid": 3838, "max_output_len": 16384}}

In general I prefer avoiding real code because it will look
out-of-date quickly.
Why not demonstrating telemetry with a cooking recipe or NASA rocket?

[...]
> +For more information on the range of data functions available in the API,
> +please refer to the docs.

"the docs"? Can we add a link?

Re: [dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides

[Power, Ciara]

Hi Thomas,

Thanks for the review.
I have addressed your comments in the v3 patch, with one exception mentioned below.


<snip>

>[...]
>> +   * List all commands.
>> +
>> +      .. code-block:: console
>
>I think you can achieve the same result as code-block with adding double
>colons (::) at the end of the previous line:
>	* List all commands::
>

I have added this in the v3 for all console code-blocks.
I left the C code-blocks as they were to ensure C syntax highlighting is maintained.

<snip>


Thanks,
Ciara

[dpdk-dev] [PATCH v3] doc: add more detail to telemetry guides

[Ciara Power]

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 <ciara.power@intel.com>

---
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
+<https://doc.dpdk.org/api/rte__telemetry_8h.html#a41dc74d561442bb6184ee6dd1f9b5bcc>`_
+
+**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 <https://doc.dpdk.org/api-20.05/rte__telemetry_8h.html>`_
+
+
+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

Re: [dpdk-dev] [PATCH v3] doc: add more detail to telemetry guides

[Power, Ciara]

>-----Original Message-----
>From: Power, Ciara <ciara.power@intel.com>
>Sent: Friday 24 July 2020 12:21
>To: Laatz, Kevin <kevin.laatz@intel.com>
>Cc: dev@dpdk.org; Richardson, Bruce <bruce.richardson@intel.com>;
>thomas@monjalon.net; Power, Ciara <ciara.power@intel.com>
>Subject: [PATCH v3] 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 <ciara.power@intel.com>
>
>---
>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
>

<snip>

I forgot to preserve the Ack from v2.

Acked-by: Bruce Richardson <bruce.richardson@intel.com>

Re: [dpdk-dev] [PATCH v3] doc: add more detail to telemetry guides

[Thomas Monjalon]

24/07/2020 13:20, Ciara Power:
> +**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.

Some variable names above needs to be enclosed in ``.

[...]
> +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::

Indent of normal text is wrong.

> -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}}

Indent issue in the section and below as well.

> +
> +
> +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"}
[...]
> +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`.

script name should be in ``


Applied with above changes.