16e9270eaSCiara Power.. SPDX-License-Identifier: BSD-3-Clause 26e9270eaSCiara Power Copyright(c) 2018 Intel Corporation. 36e9270eaSCiara Power 46e9270eaSCiara PowerDPDK Telemetry API User Guide 56e9270eaSCiara Power============================== 66e9270eaSCiara Power 76e9270eaSCiara PowerThis document describes how the Data Plane Development Kit(DPDK) Telemetry API 86e9270eaSCiara Poweris used for querying port statistics from incoming traffic. 96e9270eaSCiara Power 106e9270eaSCiara PowerIntroduction 116e9270eaSCiara Power------------ 126e9270eaSCiara Power 136e9270eaSCiara PowerThe ``librte_telemetry`` provides the functionality so that users may query 14*4080e46cSReshma Pattanmetrics from incoming port traffic and global stats(application stats). 15*4080e46cSReshma PattanThe application which initializes packet forwarding will act as the server, 16*4080e46cSReshma Pattansending metrics to the requesting application which acts as the client. 17*4080e46cSReshma Pattan 186e9270eaSCiara Power 196e9270eaSCiara PowerIn DPDK, applications are used to initialize the ``telemetry``. To view incoming 206e9270eaSCiara Powertraffic on featured ports, the application should be run first (ie. after ports 216e9270eaSCiara Powerare configured). Once the application is running, the service assurance agent 226e9270eaSCiara Power(for example the collectd plugin) should be run to begin querying the API. 236e9270eaSCiara Power 246e9270eaSCiara PowerA client connects their Service Assurance application to the DPDK application 256e9270eaSCiara Powervia a UNIX socket. Once a connection is established, a client can send JSON 266e9270eaSCiara Powermessages to the DPDK application requesting metrics via another UNIX client. 276e9270eaSCiara PowerThis request is then handled and parsed if valid. The response is then 286e9270eaSCiara Powerformatted in JSON and sent back to the requesting client. 296e9270eaSCiara Power 306e9270eaSCiara PowerPre-requisites 316e9270eaSCiara Power~~~~~~~~~~~~~~ 326e9270eaSCiara Power 33f090c23aSMarko Kovacevic* Python >= 2.5 346e9270eaSCiara Power 356e9270eaSCiara Power* Jansson library for JSON serialization 366e9270eaSCiara Power 376e9270eaSCiara PowerTest Environment 386e9270eaSCiara Power---------------- 396e9270eaSCiara Power 406e9270eaSCiara Power``telemetry`` offers a range of selftests that a client can run within 416e9270eaSCiara Powerthe DPDK application. 426e9270eaSCiara Power 436e9270eaSCiara PowerSelftests are disabled by default. They can be enabled by setting the 'selftest' 446e9270eaSCiara Powervariable to 1 in rte_telemetry_initial_accept(). 456e9270eaSCiara Power 466e9270eaSCiara PowerNote: this 'hardcoded' value is temporary. 476e9270eaSCiara Power 486e9270eaSCiara PowerConfiguration 496e9270eaSCiara Power------------- 506e9270eaSCiara Power 516e9270eaSCiara PowerEnable the telemetry API by modifying the following config option before 526e9270eaSCiara Powerbuilding DPDK:: 536e9270eaSCiara Power 546e9270eaSCiara Power CONFIG_RTE_LIBRTE_TELEMETRY=y 556e9270eaSCiara Power 566e9270eaSCiara PowerNote: Meson will pick this up automatically if ``libjansson`` is available. 576e9270eaSCiara Power 586e9270eaSCiara PowerRunning the Application 596e9270eaSCiara Power----------------------- 606e9270eaSCiara Power 616e9270eaSCiara PowerThe following steps demonstrate how to run the ``telemetry`` API to query all 626e9270eaSCiara Powerstatistics on all active ports, using the ``telemetry_client`` python script 636e9270eaSCiara Powerto query. 646e9270eaSCiara PowerNote: This guide assumes packet generation is applicable and the user is 656e9270eaSCiara Powertesting with testpmd as a DPDK primary application to forward packets, although 666e9270eaSCiara Powerany DPDK application is applicable. 676e9270eaSCiara Power 686e9270eaSCiara Power#. Launch testpmd as the primary application with ``telemetry``.:: 696e9270eaSCiara Power 706e9270eaSCiara Power ./app/testpmd --telemetry 716e9270eaSCiara Power 726e9270eaSCiara Power#. Launch the ``telemetry`` python script with a client filepath.:: 736e9270eaSCiara Power 746e9270eaSCiara Power python usertools/telemetry_client.py /var/run/some_client 756e9270eaSCiara Power 766e9270eaSCiara Power The client filepath is going to be used to setup our UNIX connection with the 776e9270eaSCiara Power DPDK primary application, in this case ``testpmd`` 786e9270eaSCiara Power This will initialize a menu where a client can proceed to recursively query 796e9270eaSCiara Power statistics, request statistics once or unregister the file_path, thus exiting 806e9270eaSCiara Power the menu. 816e9270eaSCiara Power 826e9270eaSCiara Power#. Send traffic to any or all available ports from a traffic generator. 83*4080e46cSReshma Pattan Select a query option(recursive or singular polling or global stats). 846e9270eaSCiara Power The metrics will then be displayed on the client terminal in JSON format. 856e9270eaSCiara Power 866e9270eaSCiara Power#. Once finished, unregister the client using the menu command. 87