Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/69273/?format=api
{ "id": 69273, "url": "https://patches.dpdk.org/api/patches/69273/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20200424124159.45989-19-ciara.power@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20200424124159.45989-19-ciara.power@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20200424124159.45989-19-ciara.power@intel.com", "date": "2020-04-24T12:41:59", "name": "[v4,18/18] doc: update telemetry documentation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "4a2660dcee6d259918591f781a00f903255dd02b", "submitter": { "id": 978, "url": "https://patches.dpdk.org/api/people/978/?format=api", "name": "Power, Ciara", "email": "ciara.power@intel.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20200424124159.45989-19-ciara.power@intel.com/mbox/", "series": [ { "id": 9624, "url": "https://patches.dpdk.org/api/series/9624/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=9624", "date": "2020-04-24T12:41:41", "name": "update and simplify telemetry library.", "version": 4, "mbox": "https://patches.dpdk.org/series/9624/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/69273/comments/", "check": "fail", "checks": "https://patches.dpdk.org/api/patches/69273/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from dpdk.org (dpdk.org [92.243.14.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 99614A00C2;\n\tFri, 24 Apr 2020 15:05:28 +0200 (CEST)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 7916F1D453;\n\tFri, 24 Apr 2020 15:02:38 +0200 (CEST)", "from mga02.intel.com (mga02.intel.com [134.134.136.20])\n by dpdk.org (Postfix) with ESMTP id F190A1D404\n for <dev@dpdk.org>; Fri, 24 Apr 2020 15:02:28 +0200 (CEST)", "from orsmga007.jf.intel.com ([10.7.209.58])\n by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 24 Apr 2020 06:02:28 -0700", "from silpixa00399953.ir.intel.com (HELO\n silpixa00399953.ger.corp.intel.com) ([10.237.222.53])\n by orsmga007.jf.intel.com with ESMTP; 24 Apr 2020 06:02:25 -0700" ], "IronPort-SDR": [ "\n 7qVZdmScDGXnD29WkF1VNPe3wnjo9CUs21c73ofSK5eCZRiM2B2eDsWdq1epY5wFx+4L+Ot1HC\n JC9yUd70IQhQ==", "\n LG2yGJa0lXnpl9MB70pDBxENVXWQvlxo8T/T2sKpHB3Wqqy0QfX4JBwWAk385pRC7ef30xAEkF\n dS+pEk8IMvSg==" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.73,311,1583222400\"; d=\"scan'208\";a=\"245228492\"", "From": "Ciara Power <ciara.power@intel.com>", "To": "dev@dpdk.org,\n\tkevin.laatz@intel.com", "Cc": "reshma.pattan@intel.com, jerinjacobk@gmail.com, david.marchand@redhat.com,\n keith.wiles@intel.com, mb@smartsharesystems.com, thomas@monjalon.net,\n Ciara Power <ciara.power@intel.com>", "Date": "Fri, 24 Apr 2020 13:41:59 +0100", "Message-Id": "<20200424124159.45989-19-ciara.power@intel.com>", "X-Mailer": "git-send-email 2.17.1", "In-Reply-To": "<20200424124159.45989-1-ciara.power@intel.com>", "References": "<20200319171907.60891-1-ciara.power@intel.com>\n <20200424124159.45989-1-ciara.power@intel.com>", "Subject": "[dpdk-dev] [PATCH v4 18/18] doc: update telemetry documentation", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "The existing documentation for Telemetry is updated, and further\ndocumentation is added.\n\nSigned-off-by: Ciara Power <ciara.power@intel.com>\n\n---\nv4:\n - Removed JSON API from docs as it is now internal.\n - Updated guide to show use of data functions.\n---\n doc/guides/howto/telemetry.rst | 108 ++++++++++------------\n doc/guides/linux_gsg/eal_args.include.rst | 8 ++\n doc/guides/linux_gsg/sys_reqs.rst | 2 -\n doc/guides/prog_guide/index.rst | 1 +\n doc/guides/prog_guide/telemetry_lib.rst | 61 ++++++++++++\n doc/guides/rel_notes/release_20_05.rst | 15 +++\n 6 files changed, 136 insertions(+), 59 deletions(-)\n create mode 100644 doc/guides/prog_guide/telemetry_lib.rst", "diff": "diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst\nindex cacc082161..1675f88ed6 100644\n--- a/doc/guides/howto/telemetry.rst\n+++ b/doc/guides/howto/telemetry.rst\n@@ -1,86 +1,80 @@\n .. SPDX-License-Identifier: BSD-3-Clause\n- Copyright(c) 2018 Intel Corporation.\n+ Copyright(c) 2020 Intel Corporation.\n \n-DPDK Telemetry API User Guide\n+\n+DPDK Telemetry User Guide\n ==============================\n \n-This document describes how the Data Plane Development Kit(DPDK) Telemetry API\n-is used for querying port statistics from incoming traffic.\n+The Telemetry library provides users with the ability to query DPDK for\n+telemetry information, currently including information such as ethdev stats,\n+ethdev port list, and eal parameters.\n+\n+.. Note::\n+\n+ This library is experimental and the output format may change in the future.\n+\n \n-Introduction\n-------------\n+Telemetry Interface\n+-------------------\n \n-The ``librte_telemetry`` provides the functionality so that users may query\n-metrics from incoming port traffic and global stats(application stats).\n-The application which initializes packet forwarding will act as the server,\n-sending metrics to the requesting application which acts as the client.\n+The :ref:`librte_telemetry <telemetry_library>` opens a socket with path\n+*<runtime_directory>/dpdk_telemetry.<version>*. The version represents the\n+telemetry version, the latest is v2. For example, a client would connect to a\n+socket with path */var/run/dpdk/\\*/dpdk_telemetry.v2* (when the primary process\n+is run by a root user).\n \n \n-In DPDK, applications are used to initialize the ``telemetry``. To view incoming\n-traffic on featured ports, the application should be run first (ie. after ports\n-are configured). Once the application is running, the service assurance agent\n-(for example the collectd plugin) should be run to begin querying the API.\n+Telemetry Initialization\n+------------------------\n \n-A client connects their Service Assurance application to the DPDK application\n-via a UNIX socket. Once a connection is established, a client can send JSON\n-messages to the DPDK application requesting metrics via another UNIX client.\n-This request is then handled and parsed if valid. The response is then\n-formatted in JSON and sent back to the requesting client.\n+The library is enabled by default, however an EAL flag to enable the library\n+exists, to provide backward compatibility for the previous telemetry library\n+interface.\n \n-Pre-requisites\n-~~~~~~~~~~~~~~\n+.. code-block:: console\n \n-* Python >= 2.5\n+ --telemetry\n \n-* Jansson library for JSON serialization\n+A flag exists to disable Telemetry also.\n \n-Test Environment\n-----------------\n+.. code-block:: console\n \n-``telemetry`` offers a range of selftests that a client can run within\n-the DPDK application.\n+ --no-telemetry\n \n-Selftests are disabled by default. They can be enabled by setting the 'selftest'\n-variable to 1 in rte_telemetry_initial_accept().\n \n-Note: this 'hardcoded' value is temporary.\n+Running Telemetry\n+-----------------\n \n-Configuration\n--------------\n+The following steps show how to run an application with telemetry support,\n+and query information using the telemetry client python script.\n \n-Enable the telemetry API by modifying the following config option before\n-building DPDK::\n+#. Launch testpmd as the primary application with telemetry.\n \n- CONFIG_RTE_LIBRTE_TELEMETRY=y\n+ .. code-block:: console\n \n-Note: Meson will pick this up automatically if ``libjansson`` is available.\n+ ./app/dpdk-testpmd\n \n-Running the Application\n------------------------\n+#. Launch the telemetry client script.\n \n-The following steps demonstrate how to run the ``telemetry`` API to query all\n-statistics on all active ports, using the ``telemetry_client`` python script\n-to query.\n-Note: This guide assumes packet generation is applicable and the user is\n-testing with testpmd as a DPDK primary application to forward packets, although\n-any DPDK application is applicable.\n+ .. code-block:: console\n \n-#. Launch testpmd as the primary application with ``telemetry``.::\n+ python usertools/dpdk-telemetry.py\n \n- ./app/testpmd --telemetry\n+#. When connected, the script displays the following, waiting for user input.\n \n-#. Launch the ``telemetry`` python script with a client filepath.::\n+ .. code-block:: console\n \n- python usertools/telemetry_client.py /var/run/some_client\n+ Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2\n+ {\"version\": \"DPDK 20.05.0-rc0\", \"pid\": 60285, \"max_output_len\": 16384}\n+ -->\n \n- The client filepath is going to be used to setup our UNIX connection with the\n- DPDK primary application, in this case ``testpmd``\n- This will initialize a menu where a client can proceed to recursively query\n- statistics, request statistics once or unregister the file_path, thus exiting\n- the menu.\n+#. The user can now input commands to send across the socket, and receive the\n+ response.\n \n-#. Send traffic to any or all available ports from a traffic generator.\n- Select a query option(recursive or singular polling or global stats).\n- The metrics will then be displayed on the client terminal in JSON format.\n+ .. code-block:: console\n \n-#. Once finished, unregister the client using the menu command.\n+ --> /\n+ {\"/\": [\"/\", \"/eal/app_params\", \"/eal/params\", \"/ethdev/list\",\n+ \"/ethdev/link_status\", \"/ethdev/xstats\", \"/help\", \"/info\"]}\n+ --> /ethdev/list\n+ {\"/ethdev/list\": [0, 1]}\ndiff --git a/doc/guides/linux_gsg/eal_args.include.rst b/doc/guides/linux_gsg/eal_args.include.rst\nindex 361c7cf67f..d59b1737d7 100644\n--- a/doc/guides/linux_gsg/eal_args.include.rst\n+++ b/doc/guides/linux_gsg/eal_args.include.rst\n@@ -202,3 +202,11 @@ Other options\n * ``mbuf-pool-ops-name``:\n \n Pool ops name for mbuf to use.\n+\n+* ``--telemetry``:\n+\n+ Enable telemetry (enabled by default).\n+\n+* ``--no-telemetry``:\n+\n+ Disable telemetry.\ndiff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst\nindex 7c47ec04ce..a124656bcb 100644\n--- a/doc/guides/linux_gsg/sys_reqs.rst\n+++ b/doc/guides/linux_gsg/sys_reqs.rst\n@@ -95,8 +95,6 @@ For libraries the additional dependencies include:\n \n * libarchive: for some unit tests using tar to get their resources.\n \n-* jansson: to compile and use the telemetry library.\n-\n * libelf: to compile and use the bpf library.\n \n For poll-mode drivers, the additional dependencies for each driver can be\ndiff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst\nindex 1d0cd49cd7..267839763d 100644\n--- a/doc/guides/prog_guide/index.rst\n+++ b/doc/guides/prog_guide/index.rst\n@@ -58,6 +58,7 @@ Programmer's Guide\n metrics_lib\n bpf_lib\n ipsec_lib\n+ telemetry_lib\n source_org\n dev_kit_build_system\n dev_kit_root_make_help\ndiff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst\nnew file mode 100644\nindex 0000000000..db39d0552c\n--- /dev/null\n+++ b/doc/guides/prog_guide/telemetry_lib.rst\n@@ -0,0 +1,61 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2020 Intel Corporation.\n+\n+.. _telemetry_library:\n+\n+\n+Telemetry Library\n+=================\n+\n+The Telemetry library provides an interface to retrieve information from a\n+variety of DPDK libraries. The library provides this information via socket\n+connection, taking requests from a connected client and replying with the JSON\n+response containing the requested telemetry information.\n+\n+Telemetry is enabled to run by default when running a DPDK application, and the\n+telemetry information from enabled libraries is made available. Libraries are\n+responsible for registering their own commands, and providing the callback\n+function that will format the library specific stats into the correct data\n+format, when requested.\n+\n+\n+Registering Commands\n+--------------------\n+\n+Libraries and applications must register commands to make their information\n+available via the Telemetry library. This involves providing a string command\n+in the required format (\"/library/command\"), and the callback function that\n+will handle formatting the information when required. An example showing ethdev\n+commands being registered is shown below:\n+\n+.. code-block:: c\n+\n+ rte_telemetry_register_cmd(\"/ethdev/list\", handle_port_list);\n+ rte_telemetry_register_cmd(\"/ethdev/xstats\", handle_port_xstats);\n+\n+\n+Formatting JSON response\n+------------------------\n+\n+The callback function provided by the library must format its telemetry\n+information in the required data format. The Telemetry library provides a data\n+utilities API to build up the response. For example, the ethdev library provides a\n+list of available ethdev ports in a formatted data response, constructed using the\n+following functions to build up the list:\n+\n+.. code-block:: c\n+\n+ rte_tel_data_start_array(d, RTE_TEL_INT_VAL);\n+ RTE_ETH_FOREACH_DEV(port_id)\n+ rte_tel_data_add_array_int(d, port_id);\n+\n+The data structure is then formatted into a JSON response before sending.\n+The resulting response shows the port list data provided above by the handler\n+function in ethdev, placed in a JSON reply by telemetry:\n+\n+.. code-block:: console\n+\n+ {\"/ethdev/list\": [0, 1]}\n+\n+For more information on the range of data functions available in the API,\n+please refer to the docs.\ndiff --git a/doc/guides/rel_notes/release_20_05.rst b/doc/guides/rel_notes/release_20_05.rst\nindex 89a94a7464..865df7ff0c 100644\n--- a/doc/guides/rel_notes/release_20_05.rst\n+++ b/doc/guides/rel_notes/release_20_05.rst\n@@ -145,6 +145,21 @@ New Features\n * Added IPsec inbound load-distribution support for ipsec-secgw application\n using NIC load distribution feature(Flow Director).\n \n+* **Updated Telemetry Library.**\n+\n+ The updated Telemetry library has many improvements on the original version\n+ to make it more accessible and scalable:\n+\n+ * It enables DPDK libraries and applications provide their own specific\n+ telemetry information, rather than being limited to what could be reported\n+ through the metrics library.\n+\n+ * It is no longer dependent on the external Jansson library, which allows\n+ Telemetry be enabled by default.\n+\n+ * The socket handling has been simplified making it easier for clients to\n+ connect and retrieve information.\n+\n \n Removed Items\n -------------\n", "prefixes": [ "v4", "18/18" ] }