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"}}