.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2018 Intel Corporation.
+ Copyright(c) 2020 Intel Corporation.
-DPDK Telemetry API User Guide
-==============================
-This document describes how the Data Plane Development Kit(DPDK) Telemetry API
-is used for querying port statistics from incoming traffic.
+DPDK Telemetry User Guide
+=========================
-Introduction
-------------
+The Telemetry library provides users with the ability to query DPDK for
+telemetry information, currently including information such as ethdev stats,
+ethdev port list, and eal parameters.
-The ``librte_telemetry`` provides the functionality so that users may query
-metrics from incoming port traffic and global stats(application stats).
-The application which initializes packet forwarding will act as the server,
-sending metrics to the requesting application which acts as the client.
+.. Note::
+ This library is experimental and the output format may change in the future.
-In DPDK, applications are used to initialize the ``telemetry``. To view incoming
-traffic on featured ports, the application should be run first (ie. after ports
-are configured). Once the application is running, the service assurance agent
-(for example the collectd plugin) should be run to begin querying the API.
-A client connects their Service Assurance application to the DPDK application
-via a UNIX socket. Once a connection is established, a client can send JSON
-messages to the DPDK application requesting metrics via another UNIX client.
-This request is then handled and parsed if valid. The response is then
-formatted in JSON and sent back to the requesting client.
+Telemetry Interface
+-------------------
-Pre-requisites
-~~~~~~~~~~~~~~
+The :doc:`../prog_guide/telemetry_lib` opens a socket with path
+*<runtime_directory>/dpdk_telemetry.<version>*. The version represents the
+telemetry version, the latest is v2. For example, a client would connect to a
+socket with path */var/run/dpdk/\*/dpdk_telemetry.v2* (when the primary process
+is run by a root user).
-* Python >= 2.5
-* Jansson library for JSON serialization
+Telemetry Initialization
+------------------------
-Test Environment
-----------------
+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.
-``telemetry`` offers a range of selftests that a client can run within
-the DPDK application.
+.. code-block:: console
-Selftests are disabled by default. They can be enabled by setting the 'selftest'
-variable to 1 in rte_telemetry_initial_accept().
+ --telemetry
-Note: this 'hardcoded' value is temporary.
+A flag exists to disable Telemetry also.
-Configuration
--------------
+.. code-block:: console
-Enable the telemetry API by modifying the following config option before
-building DPDK::
+ --no-telemetry
- CONFIG_RTE_LIBRTE_TELEMETRY=y
-Note: Meson will pick this up automatically if ``libjansson`` is available.
+Running Telemetry
+-----------------
-Running the Application
------------------------
+The following steps show how to run an application with telemetry support,
+and query information using the telemetry client python script.
-The following steps demonstrate how to run the ``telemetry`` API to query all
-statistics on all active ports, using the ``telemetry_client`` python script
-to query.
-Note: This guide assumes packet generation is applicable and the user is
-testing with testpmd as a DPDK primary application to forward packets, although
-any DPDK application is applicable.
+#. Launch testpmd as the primary application with telemetry.
-#. Launch testpmd as the primary application with ``telemetry``.::
+ .. code-block:: console
- ./app/testpmd --telemetry
+ ./app/dpdk-testpmd
-#. Launch the ``telemetry`` python script with a client filepath.::
+#. Launch the telemetry client script.
- python usertools/telemetry_client.py /var/run/some_client
+ .. code-block:: console
- The client filepath is going to be used to setup our UNIX connection with the
- DPDK primary application, in this case ``testpmd``
- This will initialize a menu where a client can proceed to recursively query
- statistics, request statistics once or unregister the file_path, thus exiting
- the menu.
+ python usertools/dpdk-telemetry.py
-#. Send traffic to any or all available ports from a traffic generator.
- Select a query option(recursive or singular polling or global stats).
- The metrics will then be displayed on the client terminal in JSON format.
+#. When connected, the script displays the following, waiting for user input.
-#. Once finished, unregister the client using the menu command.
+ .. code-block:: console
+
+ Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2
+ {"version": "DPDK 20.05.0-rc0", "pid": 60285, "max_output_len": 16384}
+ -->
+
+#. The user can now input commands to send across the socket, and receive the
+ response.
+
+ .. code-block:: console
+
+ --> /
+ {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list",
+ "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]}
+ --> /ethdev/list
+ {"/ethdev/list": [0, 1]}
--- /dev/null
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2020 Intel Corporation.
+
+Telemetry Library
+=================
+
+The Telemetry library provides an interface to retrieve information from a
+variety of DPDK libraries. The library provides this information via socket
+connection, taking requests from a connected client and replying with the JSON
+response containing the requested telemetry information.
+
+Telemetry is enabled to run by default when running a DPDK application, and the
+telemetry information from enabled libraries is made available. Libraries are
+responsible for registering their own commands, and providing the callback
+function that will format the library specific stats into the correct data
+format, when requested.
+
+
+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"), and the callback function that
+will handle formatting the information when required. An example showing ethdev
+commands being registered is shown below:
+
+.. code-block:: c
+
+ rte_telemetry_register_cmd("/ethdev/list", handle_port_list);
+ rte_telemetry_register_cmd("/ethdev/xstats", handle_port_xstats);
+
+
+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:
+
+.. 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.
git.droids-corp.org / dpdk.git / commitdiff