aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJoshua Watt <JPEWhacker@gmail.com>2020-03-09 11:33:53 -0500
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-03-12 23:03:03 +0000
commite22565968828c86983162e67f52ebb106242ca76 (patch)
tree6697d586f71973b8fd3ae0fcd024c0dcc90d7065 /doc
parent2ddb649ea31afe052f08e3969e36abf6fb515bc2 (diff)
downloadbitbake-e22565968828c86983162e67f52ebb106242ca76.tar.gz
bitbake-user-manual: Add documentation for BB_LOGCONFIG
Adds documentation describing how to use the BB_LOGCONFIG variable to enable custom logging. Signed-off-by: Joshua Watt <JPEWhacker@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/bitbake-user-manual/bitbake-user-manual-execution.xml97
-rw-r--r--doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml11
2 files changed, 108 insertions, 0 deletions
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
index 8f606676b..3b31f748c 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
+++ b/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"
+ }
+ },
+ "loggers": {
+ "BitBake.SigGen.HashEquiv": {
+ "level": "VERBOSE",
+ "handlers": ["autobuilderlog"]
+ },
+ "BitBake.RunQueue.HashEquiv": {
+ "level": "VERBOSE",
+ "handlers": ["autobuilderlog"]
+ }
+ }
+ }
+ </literallayout>
+ </para>
+ </section>
</chapter>
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
index bae01d90c..c4bd1f258 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -539,6 +539,17 @@
</glossdef>
</glossentry>
+ <glossentry id='var-bb-BB_LOGCONFIG'><glossterm>BB_LOGCONFIG</glossterm>
+ <glossdef>
+ <para>
+ Specifies the name of a config file that contains the user
+ logging configuration. See
+ <link linkend="logging">Logging</link> for additional
+ information
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
<glossdef>
<para>