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 62CFB42CB6; Wed, 14 Jun 2023 11:39:31 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E15D140E0F; Wed, 14 Jun 2023 11:39:30 +0200 (CEST) Received: from dkmailrelay1.smartsharesystems.com (smartserver.smartsharesystems.com [77.243.40.215]) by mails.dpdk.org (Postfix) with ESMTP id 306CB40DDB for ; Wed, 14 Jun 2023 11:39:29 +0200 (CEST) Received: from smartserver.smartsharesystems.com (smartserver.smartsharesys.local [192.168.4.10]) by dkmailrelay1.smartsharesystems.com (Postfix) with ESMTP id 235B7206CC; Wed, 14 Jun 2023 11:39:28 +0200 (CEST) Content-class: urn:content-classes:message MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Subject: RE: [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry X-MimeOLE: Produced By Microsoft Exchange V6.5 Date: Wed, 14 Jun 2023 11:39:25 +0200 Message-ID: <98CBD80474FA8B44BF855DF32C47DC35D879CE@smartserver.smartshare.dk> In-Reply-To: X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry Thread-Index: Admem3EBzglK678nTJ2PVxVH9j0ZuQABXVPw References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230613143355.77914-3-bruce.richardson@intel.com> <98CBD80474FA8B44BF855DF32C47DC35D879CA@smartserver.smartshare.dk> From: =?iso-8859-1?Q?Morten_Br=F8rup?= To: "Bruce Richardson" Cc: , 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 > From: Bruce Richardson [mailto:bruce.richardson@intel.com] > Sent: Wednesday, 14 June 2023 10.37 >=20 > On Tue, Jun 13, 2023 at 09:38:55PM +0200, Morten Br=F8rup wrote: > > > From: Bruce Richardson [mailto:bruce.richardson@intel.com] > > > Sent: Tuesday, 13 June 2023 16.34 > > > > > > As discussed by DPDK technical board [1], out contributor guide = should > > > > Typo: out -> our > > > > > 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 > > > --- > > > > Debug logging can be more verbose than trace in the one-off cases, = so I have > a slightly different personal preference. But perhaps this is mainly = relevant > in the abnormal execution paths, and thus already covered. > > >=20 > Feel free to suggest alternate wordings if you have any. That = particular > item is hard to come up with good guidelines for - especially ones = that are > not pages long! :-) + * For cases where a path through the code is only likely to be taken = once, + for example, initialization code, either *logging* at ``DEBUG`` = level or *tracing* may be used - + though tracing is preferred. How about adding this sentence at the end of the bullet: + though tracing is preferred. When conveying a lot of information, = *logging* with more details can supplement *tracing* with the basic = details. + * 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. Capitalize the first letter at the bullets: "* for"->"* For" and "* = where"->"* Where" >=20 > > Anyway, I agree with everything in this patch. > > > > Acked-by: Morten Br=F8rup > > >=20 > Thanks. >=20 > > You might also consider mentioning the xyz_dump(FILE *f) functions = such as > rte_mempool_list_dump(FILE *f). > > > > I find this type of semi-structured verbose dumping very useful for > investigating the state of systems in production. Our debug CLI = provides > access to these _dump() functions, including some of our own, from = various > subsystems in the application. > > >=20 > I'll try and put some mention of that in V2. >=20 > /Bruce