doc: support IPsec Multi-buffer lib v1.0
[dpdk.git] / 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       ./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"}}