doc/guides/howto/telemetry.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4
   5 DPDK Telemetry User Guide
   6 =========================
   7
   8 The Telemetry library provides users with the ability to query DPDK for
   9 telemetry information, currently including information such as ethdev stats,
  10 ethdev port list, and eal parameters.
  11
  12
  13 Telemetry Interface
  14 -------------------
  15
  16 The :doc:`../prog_guide/telemetry_lib` opens a socket with path
  17 *<runtime_directory>/dpdk_telemetry.<version>*. The version represents the
  18 telemetry version, the latest is v2. For example, a client would connect to a
  19 socket with path  */var/run/dpdk/\*/dpdk_telemetry.v2* (when the primary process
  20 is run by a root user).
  21
  22
  23 Telemetry Initialization
  24 ------------------------
  25
  26 The library is enabled by default, however an EAL flag to enable the library
  27 exists, to provide backward compatibility for the previous telemetry library
  28 interface::
  29
  30   --telemetry
  31
  32 A flag exists to disable Telemetry also::
  33
  34   --no-telemetry
  35
  36
  37 Running Telemetry
  38 -----------------
  39
  40 The following steps show how to run an application with telemetry support,
  41 and 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
  92 Connecting to Different DPDK Processes
  93 --------------------------------------
  94
  95 When multiple DPDK process instances are running on a system, the user will
  96 naturally wish to be able to select the instance to which the connection is
  97 being made. The method to select the instance depends on how the individual
  98 instances 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