Skip to contentSkip to conversation

doc: add more detail to telemetry guides

PATCH Superseded Ciara Power 3 participants 7 messages Jul 21, 2020 – Jul 30, 2020

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 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.

---
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(-)
doc/guides/howto/telemetry.rst +39 -7
index b4a34ed67..7e8a5d6f3 100644
@@ -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"}}
doc/guides/prog_guide/telemetry_lib.rst +148 -24

182 lines not on this page · raw message

Signature · 1 line
2.17.1
Acked-by on v2 1/1
#1 lore raw
Quoted 13 lines · 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.

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

Quoted 5 lines
---
 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.

#2 lore raw
In reply to Ciara Power

21/07/2020 18:09, Ciara Power:

doc/guides/howto/telemetry.rst line 4

Quoted 7 lines
doc/guides/howto/telemetry.rst +1 -0
@@ -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.

[...]

doc/guides/howto/telemetry.rst and query information using the telemetry client python script. · line 77

Quoted 3 lines
doc/guides/howto/telemetry.rst +3 -0
+   * 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::

[...]

Quoted 13 lines
doc/guides/prog_guide/telemetry_lib.rst +11 -0
+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**
+

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 61

Quoted 10 lines
doc/guides/prog_guide/telemetry_lib.rst +10 -0
+  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.

Quoted 33 lines
doc/guides/prog_guide/telemetry_lib.rst +33 -0
+
+**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;
+   }
+
+

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 104

Quoted 10 lines
doc/guides/prog_guide/telemetry_lib.rst +10 -0
+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.

[...]

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 142

Quoted 13 lines
doc/guides/prog_guide/telemetry_lib.rst +13 -0
+  .. 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?

[...]

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 160

Quoted 2 lines
doc/guides/prog_guide/telemetry_lib.rst +2 -0
+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?

#3 lore raw

Hi Thomas,

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

<snip>

Quoted 9 lines

[...]

doc/guides/howto/telemetry.rst and query information using the telemetry client python script. · line 77

Quoted 3 lines
doc/guides/howto/telemetry.rst +3 -0
+   * 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

#4 lore raw

PATCH v3 1/1 doc: add more detail to telemetry guides

In reply to 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.

---
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(-)
doc/guides/howto/telemetry.rst +40 -27
index b4a34ed674..e7b5434152 100644
@@ -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"}}
doc/guides/prog_guide/telemetry_lib.rst +132 -28

179 lines not on this page · raw message

Signature · 1 line
2.17.1
author Acked-by Bruce Richardson on v3 1/1
#5 lore raw
Quoted 38 lines

-----Original Message-----
From: Power, Ciara <[email protected]>
Sent: Friday 24 July 2020 12:21
To: Laatz, Kevin <[email protected]>
Cc: [email protected]; Richardson, Bruce <[email protected]>; [email protected]; Power, Ciara <[email protected]>
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.

---
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(-)
(quoted diff) +0 -0

b/doc/guides/howto/telemetry.rst index b4a34ed674..e7b5434152 100644

doc/guides/howto/telemetry.rst Telemetry Initialization · line 29

Quoted 1 line
doc/guides/howto/telemetry.rst +0 -0
@@ -29,17 +29,13 @@ Telemetry Initialization
 

<snip>

I forgot to preserve the Ack from v2.

#6 lore raw
In reply to Ciara Power

24/07/2020 13:20, Ciara Power:

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 51

Quoted 7 lines
doc/guides/prog_guide/telemetry_lib.rst +7 -0
+**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 ``.

[...]

Quoted 6 lines
doc/guides/prog_guide/telemetry_lib.rst +6 -0
+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:

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 102

Quoted 10 lines
doc/guides/prog_guide/telemetry_lib.rst +10 -0
+
+  .. 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.

Quoted 18 lines
doc/guides/prog_guide/telemetry_lib.rst +11 -5
-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);

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 126

Quoted 10 lines
doc/guides/prog_guide/telemetry_lib.rst +10 -0
+     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.

Quoted 15 lines
doc/guides/prog_guide/telemetry_lib.rst +15 -0
+
+
+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"}

[...]

doc/guides/prog_guide/telemetry_lib.rst function that will format the library specific stats into the correct data · line 166

Quoted 5 lines
doc/guides/prog_guide/telemetry_lib.rst +5 -0
+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.