1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. 3 4DPDK Telemetry API User Guide 5============================== 6 7This document describes how the Data Plane Development Kit(DPDK) Telemetry API 8is used for querying port statistics from incoming traffic. 9 10Introduction 11------------ 12 13The ``librte_telemetry`` provides the functionality so that users may query 14metrics from incoming port traffic and global stats(application stats). 15The application which initializes packet forwarding will act as the server, 16sending metrics to the requesting application which acts as the client. 17 18 19In DPDK, applications are used to initialize the ``telemetry``. To view incoming 20traffic on featured ports, the application should be run first (ie. after ports 21are configured). Once the application is running, the service assurance agent 22(for example the collectd plugin) should be run to begin querying the API. 23 24A client connects their Service Assurance application to the DPDK application 25via a UNIX socket. Once a connection is established, a client can send JSON 26messages to the DPDK application requesting metrics via another UNIX client. 27This request is then handled and parsed if valid. The response is then 28formatted in JSON and sent back to the requesting client. 29 30Pre-requisites 31~~~~~~~~~~~~~~ 32 33* Python >= 2.5 34 35* Jansson library for JSON serialization 36 37Test Environment 38---------------- 39 40``telemetry`` offers a range of selftests that a client can run within 41the DPDK application. 42 43Selftests are disabled by default. They can be enabled by setting the 'selftest' 44variable to 1 in rte_telemetry_initial_accept(). 45 46Note: this 'hardcoded' value is temporary. 47 48Configuration 49------------- 50 51Enable the telemetry API by modifying the following config option before 52building DPDK:: 53 54 CONFIG_RTE_LIBRTE_TELEMETRY=y 55 56Note: Meson will pick this up automatically if ``libjansson`` is available. 57 58Running the Application 59----------------------- 60 61The following steps demonstrate how to run the ``telemetry`` API to query all 62statistics on all active ports, using the ``telemetry_client`` python script 63to query. 64Note: This guide assumes packet generation is applicable and the user is 65testing with testpmd as a DPDK primary application to forward packets, although 66any DPDK application is applicable. 67 68#. Launch testpmd as the primary application with ``telemetry``.:: 69 70 ./app/testpmd --telemetry 71 72#. Launch the ``telemetry`` python script with a client filepath.:: 73 74 python usertools/telemetry_client.py /var/run/some_client 75 76 The client filepath is going to be used to setup our UNIX connection with the 77 DPDK primary application, in this case ``testpmd`` 78 This will initialize a menu where a client can proceed to recursively query 79 statistics, request statistics once or unregister the file_path, thus exiting 80 the menu. 81 82#. Send traffic to any or all available ports from a traffic generator. 83 Select a query option(recursive or singular polling or global stats). 84 The metrics will then be displayed on the client terminal in JSON format. 85 86#. Once finished, unregister the client using the menu command. 87