[bitbake-devel] [docs] [PATCH 15/15] bitbake-user-manual: Add documentation for BB_LOGCONFIG

[Joshua Watt]

On Thu, Mar 12, 2020 at 6:50 PM Rich Persaud <rp at stacktrust.org> wrote:
>
> On Mar 9, 2020, at 12:34, Joshua Watt <jpewhacker at gmail.com> wrote:
> >
> > Adds documentation describing how to use the BB_LOGCONFIG variable to
> > enable custom logging.
> >
> > Signed-off-by: Joshua Watt <JPEWhacker at gmail.com>
> > ---
> > .../bitbake-user-manual-execution.xml         | 97 +++++++++++++++++++
> > .../bitbake-user-manual-ref-variables.xml     | 11 +++
> > 2 files changed, 108 insertions(+)
> >
> > diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
> > index 8f606676b4..3b31f748cc 100644
> > --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
> > +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
> > @@ -929,4 +929,101 @@
> >             section.
> >         </para>
> >     </section>
> > +
> > +    <section id="logging">
> > +        <title>Logging</title>
> > +        <para>
> > +            In addition to the standard command line option to control how
> > +            verbose builds are when execute, bitbake also supports user defined
> > +            configuration of the
> > +            <ulink url='https://docs.python.org/3/library/logging.html'>Python logging</ulink>
> > +            facilities through the
> > +            <link linkend="var-bb-BB_LOGCONFIG"><filename>BB_LOGCONFIG</filename></link>
> > +            variable. This variable defines a json or yaml
> > +            <ulink url='https://docs.python.org/3/library/logging.config.html'>logging configuration</ulink>
> > +            that will be intelligently merged into the default configuration.
> > +            The logging configuration is merged using the following rules:
> > +            <itemizedlist>
> > +                <listitem><para>
> > +                    The user defined configuration will completely replace the default
> > +                    configuration if top level key
> > +                    <filename>bitbake_merge</filename> is set to the value
> > +                    <filename>False</filename>. In this case, all other rules
> > +                    are ignored.
> > +                </para></listitem>
> > +                <listitem><para>
> > +                    The user configuration must have a top level
> > +                    <filename>version</filename> which must match the value of
> > +                    the default configuration.
> > +                </para></listitem>
> > +                <listitem><para>
> > +                    Any keys defined in the <filename>handlers</filename>,
> > +                    <filename>formatters</filename>, or <filename>filters</filename>,
> > +                    will be merged into the same section in the default
> > +                    configuration, with the user specified keys taking
> > +                    replacing a default one if there is a conflict. In
> > +                    practice, this means that if both the default configuration
> > +                    and user configuration specify a handler named
> > +                    <filename>myhandler</filename>, the user defined one will
> > +                    replace the default. To prevent the user from inadvertently
> > +                    replacing a default handler, formatter, or filter, all of
> > +                    the default ones are named with a prefix of
> > +                    "<filename>BitBake.</filename>"
> > +                </para></listitem>
> > +                <listitem><para>
> > +                    If a logger is defined by the user with the key
> > +                    <filename>bitbake_merge</filename> set to
> > +                    <filename>False</filename>, that logger will be completely
> > +                    replaced by user configuration. In this case, no other
> > +                    rules will apply to that logger.
> > +                </listitem></para>
> > +                <listitem><para>
> > +                    All user defined <filename>filter</filename> and
> > +                    <filename>handlers</filename> properties for a given logger
> > +                    will be merged with corresponding properties from the
> > +                    default logger. For example, if the user configuration adds
> > +                    a filter called <filename>myFilter</filename> to the
> > +                    <filename>BitBake.SigGen</filename>, and the default
> > +                    configuration adds a filter called
> > +                    <filename>BitBake.defaultFilter</filename>, both filters
> > +                    will be applied to the logger
> > +                </listitem></para>
> > +            </itemizedlist>
> > +        </para>
> > +
> > +        <para>
> > +            As an example, consider the following user logging configuration
> > +            file which logs all Hash Equivalence related messages of VERBOSE or
> > +            higher to a file called <filename>hashequiv.log</filename>
> > +            <literallayout class='monospaced'>
> > +    {
> > +        "version": 1,
> > +        "handlers": {
> > +            "autobuilderlog": {
> > +                "class": "logging.FileHandler",
> > +                "formatter": "logfileFormatter",
> > +                "level": "DEBUG",
> > +                "filename": "hashequiv.log",
> > +                "mode": "w"
> > +            }
> > +        },
> > +        "formatters": {
> > +                "logfileFormatter": {
> > +                    "format": "%(name)s: %(levelname)s: %(message)s"
>
> What's the syntax for including a timestamp in the log message?  Or is that implicit?

It's not implicit, but you can add it easily with %(asctime)s. There
are also several other options:
https://docs.python.org/3/library/logging.html#logrecord-attributes

>
> Rich