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 0C18643008; Wed, 9 Aug 2023 13:58:54 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D4AB140691; Wed, 9 Aug 2023 13:58:53 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mails.dpdk.org (Postfix) with ESMTP id E285F400D6 for ; Wed, 9 Aug 2023 13:58:52 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1691582332; 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=2hOMNg0/eo/ysVN+NTsBRYF/rIebtqWie+W6mrGzhRo=; b=QQeN9GDbG9bYTcLA1+/JmKb4EYgZwAoaoVYiKY3HPQn4jjaw4JB5UGL/h8rRXOeaqcNdzw XhDBY4U8lruAWG5uuDDh/fI/tCS9eSySj8d1Ubx92eTr3rzXkVLAUvATIgincPrSvk+a+P J8CxTMurM41wdiFtAFy0aAJ5PZpuyYI= Received: from mail-lj1-f200.google.com (mail-lj1-f200.google.com [209.85.208.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-684--kKbKKwVMlqlluLHfrpuoA-1; Wed, 09 Aug 2023 07:58:51 -0400 X-MC-Unique: -kKbKKwVMlqlluLHfrpuoA-1 Received: by mail-lj1-f200.google.com with SMTP id 38308e7fff4ca-2ba0f27a4c9so38575561fa.1 for ; Wed, 09 Aug 2023 04:58:50 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691582329; x=1692187129; 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=2hOMNg0/eo/ysVN+NTsBRYF/rIebtqWie+W6mrGzhRo=; b=iJune6eR9Fy43ay1ataoJjR5bHKnchfp5wtkhyyqK1Q36xvMP0nrhvnQ/KKpRt0FQV oBEzePJ1vubgNi/8G//CdLb8M7uhmWXSUBuUTDwn6kqqrQ1DfM0k39HPVqLFENIgx3WP DPXXYrhvj6O4ipLcYZ/0ujs6HfklHfG6TRE467Z4m2UcKivMOTSSXmATADaOyw66cZAU x86PIpDURQNwbuytNyxQ2+yHYijbYfmnO5JEnwbJxg1iTqMOy2qPTkMc+MVMsNVSD9GC atwYYxBNAwUbbL8nw43tK+KDCl8lISl56MGaDZBNssQytGsB2z4cXXatg1F9tXaXjHGr U8Pg== X-Gm-Message-State: AOJu0Ywmn+m+j5jIVIX3Be7nGXM5b6Uzw73p9ibEVgz+zhdrNKJsAT8/ QtgsABVgpkOdGWW4b7ZCeORa5iw9E09DT8qoP/3pNNoYiqgaHGej6K9qV0TANnUmyOEsk/HnRgM M/bNTs0UVGmze7O5yxU0= X-Received: by 2002:a2e:a0cc:0:b0:2b6:e124:4d96 with SMTP id f12-20020a2ea0cc000000b002b6e1244d96mr1480055ljm.26.1691582329735; Wed, 09 Aug 2023 04:58:49 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEAvqEbOx1DQbwhhgL51hgeG+VVmy2Em4lLt5T0KCfa2v4jYCMCyABcZ/9lr2KbGEBQThG1zqXJv3Ll4nLB5Q4= X-Received: by 2002:a2e:a0cc:0:b0:2b6:e124:4d96 with SMTP id f12-20020a2ea0cc000000b002b6e1244d96mr1480045ljm.26.1691582329410; Wed, 09 Aug 2023 04:58:49 -0700 (PDT) MIME-Version: 1.0 References: <20220829151901.376754-1-bruce.richardson@intel.com> <20230731153902.2350026-1-bruce.richardson@intel.com> <20230731153902.2350026-3-bruce.richardson@intel.com> In-Reply-To: <20230731153902.2350026-3-bruce.richardson@intel.com> From: David Marchand Date: Wed, 9 Aug 2023 13:58:37 +0200 Message-ID: Subject: Re: [PATCH v7 2/3] log: separate logging functions out of EAL To: Bruce Richardson Cc: dev@dpdk.org, =?UTF-8?Q?Morten_Br=C3=B8rup?= , Tyler Retzlaff X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com 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 Some nits on the doc (that I can fix when applying if you are ok with them)= : On Mon, Jul 31, 2023 at 5:39=E2=80=AFPM Bruce Richardson wrote: > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides= /prog_guide/env_abstraction_layer.rst > index 93c8a031be..8033f6cebd 100644 > --- a/doc/guides/prog_guide/env_abstraction_layer.rst > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst > @@ -443,9 +443,7 @@ Per-lcore variables are implemented using *Thread Loc= al Storage* (TLS) to provid > Logs > ~~~~ > > -A logging API is provided by EAL. > -By default, in a Linux application, logs are sent to syslog and also to = the console. > -However, the log function can be overridden by the user to use a differe= nt logging mechanism. > +While originally part of EAL, DPDK logging functionality is now provided= by the :ref:`Log_Library`. :doc:`log_lib` > > Trace and Debug Functions > ^^^^^^^^^^^^^^^^^^^^^^^^^ > diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/inde= x.rst > index d89cd3edb6..ac91060992 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -12,6 +12,7 @@ Programmer's Guide > overview > source_org > env_abstraction_layer > + log_lib > service_cores > trace_lib > rcu_lib > diff --git a/doc/guides/prog_guide/log_lib.rst b/doc/guides/prog_guide/lo= g_lib.rst > new file mode 100644 > index 0000000000..706ddcfef3 > --- /dev/null > +++ b/doc/guides/prog_guide/log_lib.rst > @@ -0,0 +1,115 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2023 Intel Corporation. > + > +.. _log_library: Since we can directly point at this part of the documentation via :doc:`/path/to/log_lib`, no need for an anchor at the top of the file. > + > +Log Library > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D nit: too long by one =3D. > + > +The DPDK Log library provides the logging functionality for other DPDK l= ibraries and drivers. > +By default, in a Linux application, logs are sent to syslog and also to = the console. > +On FreeBSD and Windows applications, logs are sent only to the console. > +However, the log function can be overridden by the user to use a differe= nt logging mechanism. > + > +Log Levels > +----------- Idem. > + > +Log messages from apps and libraries are reported with a given level of = severity. > +These levels, specified in ``rte_log.h`` are (from most to least importa= nt): > + > +#. Emergency > +#. Alert > +#. Critical > +#. Error > +#. Warning > +#. Notice > +#. Information > +#. Debug > + > +At runtime, only messages of a configured level or above (i.e. of higher= importance) > +will be emitted by the application to the log output. > +That level can be configured either by the application calling the relev= ant APIs from the logging library, > +or by the user passing the ``--log-level`` parameter to the EAL via the = application. > + > +Setting Global Log Level > +~~~~~~~~~~~~~~~~~~~~~~~~~ Idem. > + > +To adjust the global log level for an application, > +just pass a numeric level or a level name to the ``--log-level`` EAL par= ameter. > +For example:: > + > + /path/to/app --log-level=3Derror > + > + /path/to/app --log-level=3Ddebug > + > + /path/to/app --log-level=3D5 # warning > + > +Within an application, the log level can be similarly set using the ``rt= e_log_set_global_level`` API. > + > +Setting Log Level for a Component > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Idem. > + > +In some cases, for example, for debugging purposes, > +it may be desirable to increase or decrease the log level for only a spe= cific component, or set of components. > +To facilitate this, the ``--log-level`` argument also accepts an, option= ally wildcarded, component name, > +along with the desired level for that component. > +For example:: > + > + /path/to/app --log-level=3Dlib.eal:crit > + > + /path/to/app --log-level=3Dlib.*:warning > + > +Within an application, the same result can be got using the ``rte_log_se= t_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. > + > +Using Logging APIs to Generate Log Messages > +-------------------------------------------- Idem. > + > +To output log messages, ``rte_log()`` API function should be used. > +As well as the log message, ``rte_log()`` takes two additional parameter= s: > + > +* The log level > +* The log component type > + --=20 David Marchand