From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 93A9942CC5; Thu, 15 Jun 2023 13:52:20 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 68E5640EE3; Thu, 15 Jun 2023 13:52:20 +0200 (CEST) Received: from mail-vs1-f54.google.com (mail-vs1-f54.google.com [209.85.217.54]) by mails.dpdk.org (Postfix) with ESMTP id 45D7640E0F for ; Thu, 15 Jun 2023 13:52:19 +0200 (CEST) Received: by mail-vs1-f54.google.com with SMTP id ada2fe7eead31-43de86a069fso1034853137.1 for ; Thu, 15 Jun 2023 04:52:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1686829938; x=1689421938; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=qW6SH1LTZUUwmLP4BAvzhb1a2qV7pwBCclO1gIzh8WQ=; b=oOm+uSOrX33LAEoGyT68oSsFGJkx3R3vojhHaGE5KmDsJJdewjYiAvzQ1rlkJxLp/q y12HNDE1aQu5E3dE0VBT0QpmKTQgEeox8+OzS5zbSsFpqExz/nBoeoEMwQ/a6U3SJ216 mNE04hYL2yuV7MF03x18JR/akzlX7l25F1q9vSYEwSbuzZtZZWxsFP52gA13QHlemuB7 diOrdTQsxkZIn4a/MWzMZlRvhmOo3WRGyUS6rfnPKIXiHmnHrJJOS9m1W3RDwYZSLQ6M FWROSVPmjwBe9d+tmT50OEqvDS7foGnNhzmAFLljp1gyzTl049MQ/h/G864s5aqJm/hm 62XQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1686829938; x=1689421938; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=qW6SH1LTZUUwmLP4BAvzhb1a2qV7pwBCclO1gIzh8WQ=; b=gdnaIf1u7fQDGxmXnTpTyxnljFpG2L7ZALFwPrG007AdstIM97fX7I5girpjjmhuPv znyf9EcGlVYH02hKggKX7R/2ehHq9mEkxJo6WD9TCAZDe23P7mCWpRckOPSaSyLc3bH+ KpPViH2pNEVnxpqck1VX7xhuARfB1MWHw27LG/duyCBGQvQrQkDVorV6R+srPmerZ1ms LkQZO1To2ULN11XdJJ459NJJ2Pno2+0ow6qAr34azybIJ2I0ZanY6EWgtJgJSLSAK5mH Q8isZo0zCx1yat2KTvgeW6lA/gG5x0ZPlv5dijHYDklScv7MqI4Obje+t4MvZi+Cz24f H+mA== X-Gm-Message-State: AC+VfDxejm0RhPPKxDsfh0FriizFpdjFeJqij2rCZcvHUmmBv6ah5NdN qQmZW4PVJHB0tjHe3E8kld2RyYccFiiqmEBXkEI= X-Google-Smtp-Source: ACHHUZ7WqfCifrvVwwZtyoymv7uFEo2On2xnqKsXDf25m6e9sxdQgyY/e2773vGd3F98VNwbtoL7aeJlUdh6lncu7Nw= X-Received: by 2002:a05:6102:537:b0:43f:5df2:5736 with SMTP id m23-20020a056102053700b0043f5df25736mr302410vsa.2.1686829938456; Thu, 15 Jun 2023 04:52:18 -0700 (PDT) MIME-Version: 1.0 References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230613143355.77914-3-bruce.richardson@intel.com> In-Reply-To: <20230613143355.77914-3-bruce.richardson@intel.com> From: Jerin Jacob Date: Thu, 15 Jun 2023 17:21:52 +0530 Message-ID: Subject: Re: [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry To: Bruce Richardson , Ferruh Yigit Cc: dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On Tue, Jun 13, 2023 at 8:04=E2=80=AFPM Bruce Richardson wrote: > > As discussed by DPDK technical board [1], out contributor guide should > include some details as to when to use logging vs tracing vs telemetry > to provide the end user with information about the running process and > the DPDK libraries it uses. > > [1] https://mails.dpdk.org/archives/dev/2023-March/265204.html > > Signed-off-by: Bruce Richardson > --- > doc/guides/contributing/coding_style.rst | 2 ++ > doc/guides/contributing/design.rst | 34 ++++++++++++++++++++++++ > doc/guides/prog_guide/telemetry_lib.rst | 2 ++ > doc/guides/prog_guide/trace_lib.rst | 2 ++ > 4 files changed, 40 insertions(+) > > diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contri= buting/coding_style.rst > index f50a78a346..13b2390d9e 100644 > --- a/doc/guides/contributing/coding_style.rst > +++ b/doc/guides/contributing/coding_style.rst > @@ -794,6 +794,8 @@ Control Statements > /* NOTREACHED */ > } > > +.. _dynamic_logging: > + > Dynamic Logging > --------------- > > diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing= /design.rst > index d24a7ff6a0..9edf3ea43b 100644 > --- a/doc/guides/contributing/design.rst > +++ b/doc/guides/contributing/design.rst > @@ -4,6 +4,40 @@ > Design > =3D=3D=3D=3D=3D=3D > > +Runtime Information - Logging, Tracing and Telemetry > +------------------------------------------------------- > + > +It is often desirable to provide information to the end-user as to what = is happening to the application at runtime. > +DPDK provides a number of built-in mechanisms to provide this introspect= ion: > + > +* :ref:`Logging` > +* :ref:`Tracing` > +* :ref:`Telemetry` > + > +Each of these has it's own strengths and suitabilities for use within DP= DK components. > + > +Below are some guidelines for when each should be used: > + > +* For reporting error conditions, or other abnormal runtime issues, *log= ging* should be used. > + Depending on the severity of the issue, the appropriate log level, for= example, > + ``ERROR``, ``WARNING`` or ``NOTICE``, should be used. > +* In general, it is not recommended that the DPDK logging functions shou= ld be used for debugging. > + Although the ``DEBUG`` log level may be used in components, it should = only be used sparingly, > + and the *tracing* functionality used instead. > + More specifically: > + > + * for cases where a path through the code is only likely to be taken o= nce, > + for example, initialization code, either *logging* at ``DEBUG`` leve= l or *tracing* may be used - > + though tracing is preferred. > + * where a path is to be taken multiple times within a short timeframe,= for example, > + datapath or regular control plane code, *tracing* should be used. If you think it makes sense, the following point may be added for trace. # Since trace is using CommonTraceFormat, it is possible to write _reusable_ post-processing tools with https://babeltrace.org/docs/v1.5/python/babeltrace/ like finding idle CPU time etc. Rest looks good to me. > + > +* For numerical or statistical data generated by a component, for exampl= e, per-packet statistics, > + *telemetry* should be used. > +* For any data where the data may need to be gathered at any point in th= e execution to help assess the state of the application component, > + for example, core configuration, device information, *telemetry* shoul= d be used. > + > + > Environment or Architecture-specific Sources > -------------------------------------------- > > diff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_gu= ide/telemetry_lib.rst > index 32f525a67f..71f8bd735e 100644 > --- a/doc/guides/prog_guide/telemetry_lib.rst > +++ b/doc/guides/prog_guide/telemetry_lib.rst > @@ -1,6 +1,8 @@ > .. SPDX-License-Identifier: BSD-3-Clause > Copyright(c) 2020 Intel Corporation. > > +.. _telemetry_library: > + > Telemetry Library > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/= trace_lib.rst > index e5718feddc..a3b8a7c2eb 100644 > --- a/doc/guides/prog_guide/trace_lib.rst > +++ b/doc/guides/prog_guide/trace_lib.rst > @@ -1,6 +1,8 @@ > .. SPDX-License-Identifier: BSD-3-Clause > Copyright(C) 2020 Marvell International Ltd. > > +.. _trace_library: > + > Trace Library > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > -- > 2.39.2 >