From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 18C71A058A; Fri, 17 Apr 2020 10:36:58 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id EACA51DEA8; Fri, 17 Apr 2020 10:36:57 +0200 (CEST) Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by dpdk.org (Postfix) with ESMTP id 226B01DE8E for ; Fri, 17 Apr 2020 10:36:57 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1587112616; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=x348ScuFbnmk4KeLXRtD62D+48MHv3YR8+icQqwWv5Y=; b=HOl1C1dbeysKZ9JzYkqoJ3Nt+g/lR0Jgtx7BcJwf9my+v+FVSJ23V6i2+QbxruEfQnSpNT 7D99C5eyGEJ8VrVHdarKhgfKMwQXMMLhsPrKwwbq1pvdMQ2GflVJK2T0WikFuNRUrmvD8Q r+xVHa3OIro8wZBmnBLs2idXPWfszhg= Received: from mail-vk1-f197.google.com (mail-vk1-f197.google.com [209.85.221.197]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-380-ZSEN2ED7MEGcPLLlAk-HEQ-1; Fri, 17 Apr 2020 04:36:52 -0400 X-MC-Unique: ZSEN2ED7MEGcPLLlAk-HEQ-1 Received: by mail-vk1-f197.google.com with SMTP id o194so620862vke.15 for ; Fri, 17 Apr 2020 01:36:52 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=HHjgqyrhbNN2DEPrKkx+NbPHOxNaB47XfpI/H/Q0R3M=; b=o593L5vS8lZhR9rTf/qemyBq1X1Q/SFwUDIjNFWDmwRaHMa/rRrW8/3YtFizWoFvXS YL3/SZvTUyGKHtLpHNHLiSYHmIb+n7tOdkqiIjw84RO0Xnz0jkp1GDakKq4a9tF5K8L3 bXWXWI68lEhwx6I3FuxKcbAvwJQYF2C8JRAJjrK/2Cit0IgUrxdnCC+WilIdXwoyaFSW d3swwy9gyH2Iz7G9QHn1J8urQN1fihMl5tswuWBXidt9ESoMcoDBdnciCbe7xCpaAtzQ FKFTYlJEo7aOk5t+4Y0TjyD5mDmFrnbZSWmw8aitoRhQFramPjW3u9Bd7lwZcgvxvEyN PLbw== X-Gm-Message-State: AGi0PuaqVuv7P+JIIlLKPAFcOgiWDbOf8oItdadxD1//K0DKSi1WYzWx FQapGVZ3L73F0FYcrHKdm40nBMbfoYjMGZPyHG6xWqIQnkcvFUyqH4qzRwtZ29kBlB12/EFfqVa f0d1f264HWT/8UQzPNR8= X-Received: by 2002:a1f:1255:: with SMTP id 82mr1575064vks.80.1587112611645; Fri, 17 Apr 2020 01:36:51 -0700 (PDT) X-Google-Smtp-Source: APiQypIpOwUFhMLy+2KrS/2Rt8jmbqjSWP1p1bjoLBm80gGlx7c6JgvOWLsw4c7wy3EpUR8JwEQsgPgV99c7nbVoH9o= X-Received: by 2002:a1f:1255:: with SMTP id 82mr1575050vks.80.1587112611328; Fri, 17 Apr 2020 01:36:51 -0700 (PDT) MIME-Version: 1.0 References: <20200403153709.3703448-1-jerinj@marvell.com> <20200413150116.734047-1-jerinj@marvell.com> <20200413150116.734047-34-jerinj@marvell.com> In-Reply-To: <20200413150116.734047-34-jerinj@marvell.com> From: David Marchand Date: Fri, 17 Apr 2020 10:36:38 +0200 Message-ID: To: Jerin Jacob Kollanukkaran Cc: Thomas Monjalon , John McNamara , Marko Kovacevic , Sunil Kumar Kori , dev , Bruce Richardson , =?UTF-8?Q?Mattias_R=C3=B6nnblom?= X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Subject: Re: [dpdk-dev] [PATCH v5 33/33] doc: add trace library guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On Mon, Apr 13, 2020 at 5:04 PM 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 > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Overview > +-------- > + > +*Tracing* is a technique used to understand what goes on in a running so= ftware > +system. The software used for tracing is called a *tracer*, which is con= ceptually > +similar to a tape recorder. When recording, specific instrumentation poi= nts > +placed in the software source code generate events that are saved on a g= iant > +tape: a trace file. The trace file then later can be opened in *trace vi= ewers* to > +visualize and analyze the trace events with timestamps and multi-core vi= ews. > +Such a mechanism will be useful for resolving a wide range of problems s= uch as > +multi-core synchronization issues, latency measurements, finding out the > +post analyses information like CPU idle time, etc that would otherwise b= e > +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 message= s, often > +in the range of thousands per second, with very little execution overhea= d. > +Logging is more appropriate for a very high-level analysis of less frequ= ent > +events: user accesses, exceptional conditions (errors and warnings, for > +example), database transactions, instant messaging communications, and s= uch. > +Simply put, logging is one of the many use cases that can be satisfied w= ith > +tracing. > + > +DPDK tracing library features > +----------------------------- > + > +- A framework to add tracepoints in control and fast APIs with minimum i= mpact 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 an= d/or > + globbing. > +- Generate trace in ``common trace format(CTF)``. ``CTF`` is an open-sou= rce trace > + format and it is compatible with ``LTTng``. > + For detailed information, refer `Common Trace Format `_ > + > +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. --=20 David Marchand