On Mon, Apr 13, 2020 at 5:04 PM <jer...@marvell.com> wrote: > diff --git a/doc/guides/prog_guide/trace_lib.rst > b/doc/guides/prog_guide/trace_lib.rst > new file mode 100644 > index 000000000..17f927584 > --- /dev/null > +++ b/doc/guides/prog_guide/trace_lib.rst > @@ -0,0 +1,334 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(C) 2020 Marvell International Ltd. > + > +Trace Library > +============= > + > +Overview > +-------- > + > +*Tracing* is a technique used to understand what goes on in a running > software > +system. The software used for tracing is called a *tracer*, which is > conceptually > +similar to a tape recorder. When recording, specific instrumentation points > +placed in the software source code generate events that are saved on a giant > +tape: a trace file. The trace file then later can be opened in *trace > viewers* to > +visualize and analyze the trace events with timestamps and multi-core views. > +Such a mechanism will be useful for resolving a wide range of problems such > as > +multi-core synchronization issues, latency measurements, finding out the > +post analyses information like CPU idle time, etc that would otherwise be > +extremely challenging. > + > +Tracing is often compared to *logging*. However, tracers and loggers are two > +different tools, serving two different purposes. Tracers are designed to > record > +much lower-level events that occur much more frequently than log messages, > often > +in the range of thousands per second, with very little execution overhead. > +Logging is more appropriate for a very high-level analysis of less frequent > +events: user accesses, exceptional conditions (errors and warnings, for > +example), database transactions, instant messaging communications, and such. > +Simply put, logging is one of the many use cases that can be satisfied with > +tracing. > + > +DPDK tracing library features > +----------------------------- > + > +- A framework to add tracepoints in control and fast APIs with minimum > impact on > + performance. Typical trace overhead is ~20 cycles and instrumentation > + overhead is 1 cycle. > +- Enable and disable the tracepoints at runtime. > +- Save the trace buffer to the filesystem at any point in time. > +- Supports ``overwrite`` and ``discard`` trace mode operations. > +- String-based tracepoint object lookup. > +- Enable and disable a set of tracepoints based on regular expression and/or > + globbing. > +- Generate trace in ``common trace format(CTF)``. ``CTF`` is an open-source > trace > + format and it is compatible with ``LTTng``. > + For detailed information, refer `Common Trace Format > <https://diamon.org/ctf/>`_ > + > +How to add a tracepoint? > +------------------------ > + > +This section steps you through the details of adding a simple tracepoint. > + > +.. _create_provider_header_file: > + > +Create the tracepoint provider header file > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
General comment on this file. Section titles should be separated from the rest with a new line. -- David Marchand
