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 .. Note::
  13
  14    This library is experimental and the output format may change in the future.
  15
  16
  17 Telemetry Interface
  18 -------------------
  19
  20 The :doc:`../prog_guide/telemetry_lib` opens a socket with path
  21 *<runtime_directory>/dpdk_telemetry.<version>*. The version represents the
  22 telemetry version, the latest is v2. For example, a client would connect to a
  23 socket with path  */var/run/dpdk/\*/dpdk_telemetry.v2* (when the primary process
  24 is run by a root user).
  25
  26
  27 Telemetry Initialization
  28 ------------------------
  29
  30 The library is enabled by default, however an EAL flag to enable the library
  31 exists, to provide backward compatibility for the previous telemetry library
  32 interface::
  33
  34   --telemetry
  35
  36 A flag exists to disable Telemetry also::
  37
  38   --no-telemetry
  39
  40
  41 Running Telemetry
  42 -----------------
  43
  44 The following steps show how to run an application with telemetry support,
  45 and query information using the telemetry client python script.
  46
  47 #. Launch testpmd as the primary application with telemetry::
  48
  49       ./app/dpdk-testpmd
  50
  51 #. Launch the telemetry client script::
  52
  53       python usertools/dpdk-telemetry.py
  54
  55 #. When connected, the script displays the following, waiting for user input::
  56
  57      Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2
  58      {"version": "DPDK 20.05.0-rc2", "pid": 60285, "max_output_len": 16384}
  59      -->
  60
  61 #. The user can now input commands to send across the socket, and receive the
  62    response. Some available commands are shown below.
  63
  64    * List all commands::
  65
  66        --> /
  67        {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list",
  68        "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]}
  69
  70    * Get the list of ethdev ports::
  71
  72        --> /ethdev/list
  73        {"/ethdev/list": [0, 1]}
  74
  75    .. Note::
  76
  77       For commands that expect a parameter, use "," to separate the command
  78       and parameter. See examples below.
  79
  80    * Get extended statistics for an ethdev port::
  81
  82        --> /ethdev/xstats,0
  83        {"/ethdev/xstats": {"rx_good_packets": 0, "tx_good_packets": 0,
  84        "rx_good_bytes": 0, "tx_good_bytes": 0, "rx_missed_errors": 0,
  85        ...
  86        "tx_priority7_xon_to_xoff_packets": 0}}
  87
  88    * Get the help text for a command. This will indicate what parameters are
  89      required. Pass the command as a parameter::
  90
  91        --> /help,/ethdev/xstats
  92        {"/help": {"/ethdev/xstats": "Returns the extended stats for a port.
  93        Parameters: int port_id"}}