1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2020 Intel Corporation. 3 4 5DPDK Telemetry User Guide 6========================= 7 8The Telemetry library provides users with the ability to query DPDK for 9telemetry information, currently including information such as ethdev stats, 10ethdev port list, and eal parameters. 11 12 13Telemetry Interface 14------------------- 15 16The :doc:`../prog_guide/telemetry_lib` opens a socket with path 17*<runtime_directory>/dpdk_telemetry.<version>*. The version represents the 18telemetry version, the latest is v2. For example, a client would connect to a 19socket with path */var/run/dpdk/\*/dpdk_telemetry.v2* (when the primary process 20is run by a root user). 21 22 23Telemetry Initialization 24------------------------ 25 26The library is enabled by default, however an EAL flag to enable the library 27exists, to provide backward compatibility for the previous telemetry library 28interface:: 29 30 --telemetry 31 32A flag exists to disable Telemetry also:: 33 34 --no-telemetry 35 36 37Running Telemetry 38----------------- 39 40The following steps show how to run an application with telemetry support, 41and query information using the telemetry client python script. 42 43#. Launch testpmd as the primary application with telemetry:: 44 45 ./app/dpdk-testpmd 46 47#. Launch the telemetry client script:: 48 49 ./usertools/dpdk-telemetry.py 50 51#. When connected, the script displays the following, waiting for user input:: 52 53 Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2 54 {"version": "DPDK 20.05.0-rc2", "pid": 60285, "max_output_len": 16384} 55 --> 56 57#. The user can now input commands to send across the socket, and receive the 58 response. Some available commands are shown below. 59 60 * List all commands:: 61 62 --> / 63 {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list", 64 "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]} 65 66 * Get the list of ethdev ports:: 67 68 --> /ethdev/list 69 {"/ethdev/list": [0, 1]} 70 71 .. Note:: 72 73 For commands that expect a parameter, use "," to separate the command 74 and parameter. See examples below. 75 76 * Get extended statistics for an ethdev port:: 77 78 --> /ethdev/xstats,0 79 {"/ethdev/xstats": {"rx_good_packets": 0, "tx_good_packets": 0, 80 "rx_good_bytes": 0, "tx_good_bytes": 0, "rx_missed_errors": 0, 81 ... 82 "tx_priority7_xon_to_xoff_packets": 0}} 83 84 * Get the help text for a command. This will indicate what parameters are 85 required. Pass the command as a parameter:: 86 87 --> /help,/ethdev/xstats 88 {"/help": {"/ethdev/xstats": "Returns the extended stats for a port. 89 Parameters: int port_id"}} 90 91 92Connecting to Different DPDK Processes 93-------------------------------------- 94 95When multiple DPDK process instances are running on a system, the user will 96naturally wish to be able to select the instance to which the connection is 97being made. The method to select the instance depends on how the individual 98instances are run: 99 100* For DPDK processes run using a non-default file-prefix, 101 i.e. using the `--file-prefix` EAL option flag, 102 the file-prefix for the process should be passed via the `-f` or `--file-prefix` script flag. 103 104 For example, to connect to testpmd run as:: 105 106 $ ./build/app/dpdk-testpmd -l 2,3 --file-prefix="tpmd" 107 108 One would use the telemetry script command:: 109 110 $ ./usertools/dpdk-telemetry -f "tpmd" 111 112 To list all running telemetry-enabled file-prefixes, the ``-l`` or ``--list`` flags can be used:: 113 114 $ ./usertools/dpdk-telemetry -l 115 116* For the case where multiple processes are run using the `--in-memory` EAL flag, 117 but no `--file-prefix` flag, or the same `--file-prefix` flag, 118 those processes will all share the same runtime directory. 119 In this case, 120 each process after the first will add an increasing count suffix to the telemetry socket name, 121 with each one taking the first available free socket name. 122 This suffix count can be passed to the telemetry script using the `-i` or `--instance` flag. 123 124 For example, if the following two applications are run in separate terminals:: 125 126 $ ./build/app/dpdk-testpmd -l 2,3 --in-memory # will use socket "dpdk_telemetry.v2" 127 128 $ ./build/app/test/dpdk-test -l 4,5 --in-memory # will use "dpdk_telemetry.v2:1" 129 130 The following telemetry script commands would allow one to connect to each binary:: 131 132 $ ./usertools/dpdk-telemetry.py # will connect to testpmd 133 134 $ ./usertools/dpdk-telemetry.py -i 1 # will connect to test binary 135