net/cnxk: make inline inbound device usage as default
[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
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