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 .. code-block:: console
  35
  36    --telemetry
  37
  38 A flag exists to disable Telemetry also.
  39
  40 .. code-block:: console
  41
  42    --no-telemetry
  43
  44
  45 Running Telemetry
  46 -----------------
  47
  48 The following steps show how to run an application with telemetry support,
  49 and query information using the telemetry client python script.
  50
  51 #. Launch testpmd as the primary application with telemetry.
  52
  53    .. code-block:: console
  54
  55       ./app/dpdk-testpmd
  56
  57 #. Launch the telemetry client script.
  58
  59    .. code-block:: console
  60
  61       python usertools/dpdk-telemetry.py
  62
  63 #. When connected, the script displays the following, waiting for user input.
  64
  65    .. code-block:: console
  66
  67       Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2
  68       {"version": "DPDK 20.05.0-rc0", "pid": 60285, "max_output_len": 16384}
  69       -->
  70
  71 #. The user can now input commands to send across the socket, and receive the
  72    response.
  73
  74    .. code-block:: console
  75
  76       --> /
  77       {"/": ["/", "/eal/app_params", "/eal/params", "/ethdev/list",
  78       "/ethdev/link_status", "/ethdev/xstats", "/help", "/info"]}
  79       --> /ethdev/list
  80       {"/ethdev/list": [0, 1]}