summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml97
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml11
2 files changed, 108 insertions, 0 deletions
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 @@
929 section. 929 section.
930 </para> 930 </para>
931 </section> 931 </section>
932
933 <section id="logging">
934 <title>Logging</title>
935 <para>
936 In addition to the standard command line option to control how
937 verbose builds are when execute, bitbake also supports user defined
938 configuration of the
939 <ulink url='https://docs.python.org/3/library/logging.html'>Python logging</ulink>
940 facilities through the
941 <link linkend="var-bb-BB_LOGCONFIG"><filename>BB_LOGCONFIG</filename></link>
942 variable. This variable defines a json or yaml
943 <ulink url='https://docs.python.org/3/library/logging.config.html'>logging configuration</ulink>
944 that will be intelligently merged into the default configuration.
945 The logging configuration is merged using the following rules:
946 <itemizedlist>
947 <listitem><para>
948 The user defined configuration will completely replace the default
949 configuration if top level key
950 <filename>bitbake_merge</filename> is set to the value
951 <filename>False</filename>. In this case, all other rules
952 are ignored.
953 </para></listitem>
954 <listitem><para>
955 The user configuration must have a top level
956 <filename>version</filename> which must match the value of
957 the default configuration.
958 </para></listitem>
959 <listitem><para>
960 Any keys defined in the <filename>handlers</filename>,
961 <filename>formatters</filename>, or <filename>filters</filename>,
962 will be merged into the same section in the default
963 configuration, with the user specified keys taking
964 replacing a default one if there is a conflict. In
965 practice, this means that if both the default configuration
966 and user configuration specify a handler named
967 <filename>myhandler</filename>, the user defined one will
968 replace the default. To prevent the user from inadvertently
969 replacing a default handler, formatter, or filter, all of
970 the default ones are named with a prefix of
971 "<filename>BitBake.</filename>"
972 </para></listitem>
973 <listitem><para>
974 If a logger is defined by the user with the key
975 <filename>bitbake_merge</filename> set to
976 <filename>False</filename>, that logger will be completely
977 replaced by user configuration. In this case, no other
978 rules will apply to that logger.
979 </listitem></para>
980 <listitem><para>
981 All user defined <filename>filter</filename> and
982 <filename>handlers</filename> properties for a given logger
983 will be merged with corresponding properties from the
984 default logger. For example, if the user configuration adds
985 a filter called <filename>myFilter</filename> to the
986 <filename>BitBake.SigGen</filename>, and the default
987 configuration adds a filter called
988 <filename>BitBake.defaultFilter</filename>, both filters
989 will be applied to the logger
990 </listitem></para>
991 </itemizedlist>
992 </para>
993
994 <para>
995 As an example, consider the following user logging configuration
996 file which logs all Hash Equivalence related messages of VERBOSE or
997 higher to a file called <filename>hashequiv.log</filename>
998 <literallayout class='monospaced'>
999 {
1000 "version": 1,
1001 "handlers": {
1002 "autobuilderlog": {
1003 "class": "logging.FileHandler",
1004 "formatter": "logfileFormatter",
1005 "level": "DEBUG",
1006 "filename": "hashequiv.log",
1007 "mode": "w"
1008 }
1009 },
1010 "formatters": {
1011 "logfileFormatter": {
1012 "format": "%(name)s: %(levelname)s: %(message)s"
1013 }
1014 },
1015 "loggers": {
1016 "BitBake.SigGen.HashEquiv": {
1017 "level": "VERBOSE",
1018 "handlers": ["autobuilderlog"]
1019 },
1020 "BitBake.RunQueue.HashEquiv": {
1021 "level": "VERBOSE",
1022 "handlers": ["autobuilderlog"]
1023 }
1024 }
1025 }
1026 </literallayout>
1027 </para>
1028 </section>
932</chapter> 1029</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
index bae01d90c0..c4bd1f2584 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -539,6 +539,17 @@
539 </glossdef> 539 </glossdef>
540 </glossentry> 540 </glossentry>
541 541
542 <glossentry id='var-bb-BB_LOGCONFIG'><glossterm>BB_LOGCONFIG</glossterm>
543 <glossdef>
544 <para>
545 Specifies the name of a config file that contains the user
546 logging configuration. See
547 <link linkend="logging">Logging</link> for additional
548 information
549 </para>
550 </glossdef>
551 </glossentry>
552
542 <glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm> 553 <glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
543 <glossdef> 554 <glossdef>
544 <para> 555 <para>