[dpdk-dev] [PATCH v5 33/33] doc: add trace library guide

David Marchand david.marchand at redhat.com
Fri Apr 17 10:36:38 CEST 2020


On Mon, Apr 13, 2020 at 5:04 PM <jerinj at 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



More information about the dev mailing list