app/testpmd: add flow table management
[dpdk.git] / doc / guides / prog_guide / trace_lib.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(C) 2020 Marvell International Ltd.
3
4 Trace Library
5 =============
6
7 Overview
8 --------
9
10 *Tracing* is a technique used to understand what goes on in a running software
11 system. The software used for tracing is called a *tracer*, which is
12 conceptually similar to a tape recorder.
13 When recording, specific instrumentation points placed in the software source
14 code generate events that are saved on a giant tape: a trace file.
15 The trace file then later can be opened in *trace viewers* to visualize and
16 analyze the trace events with timestamps and multi-core views.
17 Such a mechanism will be useful for resolving a wide range of problems such as
18 multi-core synchronization issues, latency measurements, finding out the
19 post analysis information like CPU idle time, etc that would otherwise be
20 extremely challenging to get.
21
22 Tracing is often compared to *logging*. However, tracers and loggers are two
23 different tools, serving two different purposes.
24 Tracers are designed to record much lower-level events that occur much more
25 frequently than log messages, often in the range of thousands per second, with
26 very little execution overhead.
27 Logging is more appropriate for a very high-level analysis of less frequent
28 events: user accesses, exceptional conditions (errors and warnings, for
29 example), database transactions, instant messaging communications, and such.
30 Simply put, logging is one of the many use cases that can be satisfied with
31 tracing.
32
33 DPDK tracing library features
34 -----------------------------
35
36 - A framework to add tracepoints in control and fast path APIs with minimum
37   impact on performance.
38   Typical trace overhead is ~20 cycles and instrumentation overhead is 1 cycle.
39 - Enable and disable the tracepoints at runtime.
40 - Save the trace buffer to the filesystem at any point in time.
41 - Support ``overwrite`` and ``discard`` trace mode operations.
42 - String-based tracepoint object lookup.
43 - Enable and disable a set of tracepoints based on regular expression and/or
44   globbing.
45 - Generate trace in ``Common Trace Format (CTF)``. ``CTF`` is an open-source
46   trace format and is compatible with ``LTTng``.
47   For detailed information, refer to
48   `Common Trace Format <https://diamon.org/ctf/>`_.
49
50 How to add a tracepoint?
51 ------------------------
52
53 This section steps you through the details of adding a simple tracepoint.
54
55 .. _create_tracepoint_header_file:
56
57 Create the tracepoint header file
58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60 .. code-block:: c
61
62  #include <rte_trace_point.h>
63
64  RTE_TRACE_POINT(
65         app_trace_string,
66         RTE_TRACE_POINT_ARGS(const char *str),
67         rte_trace_point_emit_string(str);
68  )
69
70 The above macro creates ``app_trace_string`` tracepoint.
71 The user can choose any name for the tracepoint.
72 However, when adding a tracepoint in the DPDK library, the
73 ``rte_<library_name>_trace_[<domain>_]<name>`` naming convention must be
74 followed.
75 The examples are ``rte_eal_trace_generic_str``, ``rte_mempool_trace_create``.
76
77 The ``RTE_TRACE_POINT`` macro expands from above definition as the following
78 function template:
79
80 .. code-block:: c
81
82  static __rte_always_inline void
83  app_trace_string(const char *str)
84  {
85          /* Trace subsystem hooks */
86          ...
87          rte_trace_point_emit_string(str);
88  }
89
90 The consumer of this tracepoint can invoke
91 ``app_trace_string(const char *str)`` to emit the trace event to the trace
92 buffer.
93
94 Register the tracepoint
95 ~~~~~~~~~~~~~~~~~~~~~~~
96
97 .. code-block:: c
98
99  #include <rte_trace_point_register.h>
100
101  #include <my_tracepoint.h>
102
103  RTE_TRACE_POINT_REGISTER(app_trace_string, app.trace.string)
104
105 The above code snippet registers the ``app_trace_string`` tracepoint to
106 trace library. Here, the ``my_tracepoint.h`` is the header file
107 that the user created in the first step :ref:`create_tracepoint_header_file`.
108
109 The second argument for the ``RTE_TRACE_POINT_REGISTER`` is the name for the
110 tracepoint. This string will be used for tracepoint lookup or regular
111 expression and/or glob based tracepoint operations.
112 There is no requirement for the tracepoint function and its name to be similar.
113 However, it is recommended to have a similar name for a better naming
114 convention.
115
116 .. note::
117
118    The ``rte_trace_point_register.h`` header must be included before any
119    inclusion of the ``rte_trace_point.h`` header.
120
121 .. note::
122
123    The ``RTE_TRACE_POINT_REGISTER`` defines the placeholder for the
124    ``rte_trace_point_t`` tracepoint object. The user must export a
125    ``__<trace_function_name>`` symbol in the library ``.map`` file for this
126    tracepoint to be used out of the library, in shared builds.
127    For example, ``__app_trace_string`` will be the exported symbol in the
128    above example.
129
130 Fast path tracepoint
131 --------------------
132
133 In order to avoid performance impact in fast path code, the library introduced
134 ``RTE_TRACE_POINT_FP``. When adding the tracepoint in fast path code,
135 the user must use ``RTE_TRACE_POINT_FP`` instead of ``RTE_TRACE_POINT``.
136
137 ``RTE_TRACE_POINT_FP`` is compiled out by default and it can be enabled using
138 the ``enable_trace_fp`` option for meson build.
139
140 Event record mode
141 -----------------
142
143 Event record mode is an attribute of trace buffers. Trace library exposes the
144 following modes:
145
146 Overwrite
147    When the trace buffer is full, new trace events overwrites the existing
148    captured events in the trace buffer.
149 Discard
150    When the trace buffer is full, new trace events will be discarded.
151
152 The mode can be configured either using EAL command line parameter
153 ``--trace-mode`` on application boot up or use ``rte_trace_mode_set()`` API to
154 configure at runtime.
155
156 Trace file location
157 -------------------
158
159 On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
160 the trace buffers to the filesystem. By default, the trace files are stored in
161 ``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``.
162 It can be overridden by the ``--trace-dir=<directory path>`` EAL command line
163 option.
164
165 For more information, refer to :doc:`../linux_gsg/linux_eal_parameters` for
166 trace EAL command line options.
167
168 View and analyze the recorded events
169 ------------------------------------
170
171 Once the trace directory is available, the user can view/inspect the recorded
172 events.
173
174 There are many tools you can use to read DPDK traces:
175
176 1. ``babeltrace`` is a command-line utility that converts trace formats; it
177 supports the format that DPDK trace library produces, CTF, as well as a
178 basic text output that can be grep'ed.
179 The babeltrace command is part of the Open Source Babeltrace project.
180
181 2. ``Trace Compass`` is a graphical user interface for viewing and analyzing
182 any type of logs or traces, including DPDK traces.
183
184 Use the babeltrace command-line tool
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186
187 The simplest way to list all the recorded events of a trace is to pass its path
188 to babeltrace with no options::
189
190     babeltrace </path-to-trace-events/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/>
191
192 ``babeltrace`` finds all traces recursively within the given path and prints
193 all their events, merging them in chronological order.
194
195 You can pipe the output of the babeltrace into a tool like grep(1) for further
196 filtering. Below example grep the events for ``ethdev`` only::
197
198     babeltrace /tmp/my-dpdk-trace | grep ethdev
199
200 You can pipe the output of babeltrace into a tool like wc(1) to count the
201 recorded events. Below example count the number of ``ethdev`` events::
202
203     babeltrace /tmp/my-dpdk-trace | grep ethdev | wc --lines
204
205 Use the tracecompass GUI tool
206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207
208 ``Tracecompass`` is another tool to view/analyze the DPDK traces which gives
209 a graphical view of events. Like ``babeltrace``, tracecompass also provides
210 an interface to search for a particular event.
211 To use ``tracecompass``, following are the minimum required steps:
212
213 - Install ``tracecompass`` to the localhost. Variants are available for Linux,
214   Windows, and OS-X.
215 - Launch ``tracecompass`` which will open a graphical window with trace
216   management interfaces.
217 - Open a trace using ``File->Open Trace`` option and select metadata file which
218   is to be viewed/analyzed.
219
220 For more details, refer
221 `Trace Compass <https://www.eclipse.org/tracecompass/>`_.
222
223 Quick start
224 -----------
225
226 This section steps you through the details of generating trace and viewing it.
227
228 - Start the dpdk-test::
229
230     echo "quit" | ./build/app/test/dpdk-test --no-huge --trace=.*
231
232 - View the traces with babeltrace viewer::
233
234     babeltrace $HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/
235
236 Implementation details
237 ----------------------
238
239 As DPDK trace library is designed to generate traces that uses ``Common Trace
240 Format (CTF)``. ``CTF`` specification consists of the following units to create
241 a trace.
242
243 - ``Stream`` Sequence of packets.
244 - ``Packet`` Header and one or more events.
245 - ``Event`` Header and payload.
246
247 For detailed information, refer to
248 `Common Trace Format <https://diamon.org/ctf/>`_.
249
250 The implementation details broadly divided into the following areas:
251
252 Trace metadata creation
253 ~~~~~~~~~~~~~~~~~~~~~~~
254
255 Based on the ``CTF`` specification, one of a CTF trace's streams is mandatory:
256 the metadata stream. It contains exactly what you would expect: data about the
257 trace itself. The metadata stream contains a textual description of the binary
258 layouts of all the other streams.
259
260 This description is written using the Trace Stream Description Language (TSDL),
261 a declarative language that exists only in the realm of CTF.
262 The purpose of the metadata stream is to make CTF readers know how to parse a
263 trace's binary streams of events without CTF specifying any fixed layout.
264 The only stream layout known in advance is, in fact, the metadata stream's one.
265
266 The internal ``trace_metadata_create()`` function generates the metadata.
267
268 Trace memory
269 ~~~~~~~~~~~~
270
271 The trace memory will be allocated through an internal function
272 ``__rte_trace_mem_per_thread_alloc()``. The trace memory will be allocated
273 per thread to enable lock less trace-emit function.
274 The memory for the trace memory for DPDK lcores will be allocated on
275 ``rte_eal_init()`` if the trace is enabled through a EAL option.
276 For non DPDK threads, on the first trace emission, the memory will be
277 allocated.
278
279 Trace memory layout
280 ~~~~~~~~~~~~~~~~~~~
281
282 .. _table_trace_mem_layout:
283
284 .. table:: Trace memory layout.
285
286   +-------------------+
287   |   packet.header   |
288   +-------------------+
289   |   packet.context  |
290   +-------------------+
291   |   trace 0 header  |
292   +-------------------+
293   |   trace 0 payload |
294   +-------------------+
295   |   trace 1 header  |
296   +-------------------+
297   |   trace 1 payload |
298   +-------------------+
299   |   trace N header  |
300   +-------------------+
301   |   trace N payload |
302   +-------------------+
303
304 packet.header
305 ^^^^^^^^^^^^^
306
307 .. _table_packet_header:
308
309 .. table:: Packet header layout.
310
311   +-------------------+
312   |   uint32_t magic  |
313   +-------------------+
314   |   rte_uuid_t uuid |
315   +-------------------+
316
317 packet.context
318 ^^^^^^^^^^^^^^
319
320 .. _table_packet_context:
321
322 .. table:: Packet context layout.
323
324   +----------------------+
325   |  uint32_t thread_id  |
326   +----------------------+
327   | char thread_name[32] |
328   +----------------------+
329
330 trace.header
331 ^^^^^^^^^^^^
332
333 .. _table_trace_header:
334
335 .. table:: Trace header layout.
336
337   +----------------------+
338   | event_id  [63:48]    |
339   +----------------------+
340   | timestamp [47:0]     |
341   +----------------------+
342
343 The trace header is 64 bits, it consists of 48 bits of timestamp and 16 bits
344 event ID.
345
346 The ``packet.header`` and ``packet.context`` will be written in the slow path
347 at the time of trace memory creation. The ``trace.header`` and trace payload
348 will be emitted when the tracepoint function is invoked.