X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fhowto%2Ftelemetry.rst;h=0464c431feecdd9d7887ed8780cb26a02a1d6b5f;hb=b54403fd08374dae243bf0a0e90488f51485154e;hp=00f8f7a85c3d8499e408b45a3d6ad34a9935c690;hpb=f090c23a04fa36b0114644368f6b0b75ef1198bf;p=dpdk.git diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst index 00f8f7a85c..0464c431fe 100644 --- a/doc/guides/howto/telemetry.rst +++ b/doc/guides/howto/telemetry.rst @@ -1,85 +1,134 @@ .. 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. The application which initializes packet -forwarding will act as the server, sending metrics to the requesting application -which acts as the client. -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. +Telemetry Interface +------------------- -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. +The :doc:`../prog_guide/telemetry_lib` opens a socket with path +*/dpdk_telemetry.*. 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). -Pre-requisites -~~~~~~~~~~~~~~ -* Python >= 2.5 +Telemetry Initialization +------------------------ -* Jansson library for JSON serialization +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:: -Test Environment ----------------- + --telemetry -``telemetry`` offers a range of selftests that a client can run within -the DPDK application. +A flag exists to disable Telemetry also:: -Selftests are disabled by default. They can be enabled by setting the 'selftest' -variable to 1 in rte_telemetry_initial_accept(). + --no-telemetry -Note: this 'hardcoded' value is temporary. -Configuration -------------- +Running Telemetry +----------------- -Enable the telemetry API by modifying the following config option before -building DPDK:: +The following steps show how to run an application with telemetry support, +and query information using the telemetry client python script. - CONFIG_RTE_LIBRTE_TELEMETRY=y +#. Launch testpmd as the primary application with telemetry:: -Note: Meson will pick this up automatically if ``libjansson`` is available. + ./app/dpdk-testpmd -Running the Application ------------------------ +#. Launch the telemetry client 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. + ./usertools/dpdk-telemetry.py -#. Launch testpmd as the primary application with ``telemetry``.:: +#. When connected, the script displays the following, waiting for user input:: - ./app/testpmd --telemetry + Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2 + {"version": "DPDK 20.05.0-rc2", "pid": 60285, "max_output_len": 16384} + --> -#. Launch the ``telemetry`` python script with a client filepath.:: +#. The user can now input commands to send across the socket, and receive the + response. Some available commands are shown below. - python usertools/telemetry_client.py /var/run/some_client + * List all commands:: - 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. + --> / + {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list", + "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]} -#. Send traffic to any or all available ports from a traffic generator. - Select a query option(recursive or singular polling). - The metrics will then be displayed on the client terminal in JSON format. + * Get the list of ethdev ports:: -#. Once finished, unregister the client using the menu command. + --> /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}} + + * Get the help text for a command. This will indicate what parameters are + required. Pass the command as a parameter:: + + --> /help,/ethdev/xstats + {"/help": {"/ethdev/xstats": "Returns the extended stats for a port. + Parameters: int port_id"}} + + +Connecting to Different DPDK Processes +-------------------------------------- + +When multiple DPDK process instances are running on a system, the user will +naturally wish to be able to select the instance to which the connection is +being made. The method to select the instance depends on how the individual +instances are run: + +* For DPDK processes run using a non-default file-prefix, + i.e. using the `--file-prefix` EAL option flag, + the file-prefix for the process should be passed via the `-f` or `--file-prefix` script flag. + + For example, to connect to testpmd run as:: + + $ ./build/app/dpdk-testpmd -l 2,3 --file-prefix="tpmd" + + One would use the telemetry script command:: + + $ ./usertools/dpdk-telemetry -f "tpmd" + + To list all running telemetry-enabled file-prefixes, the ``-l`` or ``--list`` flags can be used:: + + $ ./usertools/dpdk-telemetry -l + +* For the case where multiple processes are run using the `--in-memory` EAL flag, + but no `--file-prefix` flag, or the same `--file-prefix` flag, + those processes will all share the same runtime directory. + In this case, + each process after the first will add an increasing count suffix to the telemetry socket name, + with each one taking the first available free socket name. + This suffix count can be passed to the telemetry script using the `-i` or `--instance` flag. + + For example, if the following two applications are run in separate terminals:: + + $ ./build/app/dpdk-testpmd -l 2,3 --in-memory # will use socket "dpdk_telemetry.v2" + + $ ./build/app/test/dpdk-test -l 4,5 --in-memory # will use "dpdk_telemetry.v2:1" + + The following telemetry script commands would allow one to connect to each binary:: + + $ ./usertools/dpdk-telemetry.py # will connect to testpmd + + $ ./usertools/dpdk-telemetry.py -i 1 # will connect to test binary