Changes between Initial Version and Version 1 of VBoxLogging

Timestamp:

Aug 22, 2011 11:51:38 AM (13 years ago)

Author:

Michael Thayer

Comment:

Public documentation for the iprt logging facility

VBoxLogging

@@ +1 @@
+= The VirtualBox/IPRT logging facility =
+
+The generic description of the IPRT logging facility is found [http://www.virtualbox.org/browser/trunk/src/VBox/Runtime/VBox/log-vbox.cpp#L27 here].
+
+IPRT log group names are found in source:trunk/include/iprt/log.h [[BR]]
+!VirtualBox log group names are found in source:trunk/include/VBox/log.h
+
+!VirtualBox uses the env.vars `VBOX_LOG`, `VBOX_LOG_DEST` and `VBOX_LOG_FLAGS` to
+control debug log output and `VBOX_RELEASE_LOG`, `VBOX_RELEASE_LOG_DEST` and
+`VBOX_RELEASE_LOG_FLAGS` to control release log output.  Logging settings can also be
+changed at runtime using the debugger.
+
+Examples:
+
+{{{
+set VBOX_LOG=em=~0 rem* -rem_mmio
+set VBOX_LOG_FLAGS=buffered thread tsc
+}}}
+
+{{{
+export VBOX_RELEASE_LOG="rem*.e.l.f main gui"
+export VBOX_RELEASE_LOG_FLAGS="buffered thread msprog"
+}}}
+
+{{{
+export VBOX_LOG="dev_vmm"
+export VBOX_LOG_FLAGS="msprog"
+export VBOX_LOG_DEST="nofile stderr"
+}}}
+
+The release logging even prints information to a destination when running a release
+build of component/program. By default this destination is the release log file in the user's
+!VirtualBox home directory, which is rotated on creation. To set the destination, use the
+environment variable "VBOX_LOG_DEST" for debug logging and "VBOX_RELEASE_LOG_DEST" for
+release logging, add the prefix "file=" (if logging to a file) or "dir=" (directory) plus
+the file name / directory. See "Runtime\common\log\log.cpp" around line 300.
+
+By default, all level 1 release log statements ("!LogRel()") cause logging to the release log.
+For level 2 ("LogRel2()"), flow logging ("!LogRelFlow()") etc to be written out, you need to
+enable the logging types for the log groups you are interested in - e.g.
+{{{
+VBOX_RELEASE_LOG="+dev_vmm.e.l.f+main.e.l.f"
+}}}
+would enable the "dev_vmm" and "main" release log groups for level 2 and flow logging.
+Release logging can be handy for debugging remote problems, but should of course be used
+sparingly in performance-critical code.
+
+To enable ring-0 logging add VBOX_WITH_R0_LOGGING=1 to !LocalConfig.kmk or pass it to kmk in the command line (this part is not necessary for guest ring-0 logging) and set up loggging preferences in the source file src/VBox/Runtime/VBox/log-vbox.cpp.
+
+Some notes about group suffixes:[[BR]]
+.eo (.enabledonly) - enabled only;[[BR]]
+.e (.enabled) - enabled + level1;[[BR]]
+.lX (.levelX) - level X , X 1-6 ;[[BR]]
+.l = .l2;[[BR]]
+.f (.flow);[[BR]]
+
+named suffixes:[[BR]]
+Sometimes core developers use private logging statements which look like Log<Nick>(...), where <Nick> is the developer's nickname.  To enable those logging statements you must set the log flag for that developer.  For example, for the developer with the nick "NoName" (LogNoName(...) statements in the code) use the suffix[[BR]]
+.n = .noname;[[BR]]
+
+To control where logging output/files go(es), use the VBOX_LOG_DEST variable, e.g.:
+
+{{{
+export VBOX_LOG_DEST="dir=c:\temp"
+}}}
+
+
+To disable logging entirely, use one of:
+
+{{{
+export VBOX_LOG_DEST=nofile
+export VBOX_LOG_FLAGS=disabled
+export VBOX_LOG=-all
+}}}
+
+To enable Guest Additions logging, add to the host environment variables:
+
+{{{
+set VBOX_LOG="-all+dev_vmm_backdoor.e.l.f+dev_vmm.e.l.f"
+set VBOX_LOG_FLAGS="thread tsc"
+}}}
+
+... and on the guest (for doing this in ring-0 bits see the section on ring-0 above):
+
+{{{
+set VBOX_LOG="all"
+}}}
+
+'''Note:''' You need to have the '''debug''' Guest Additions (that is, a debug version of VBoxGuest.<ext>) installed on the guest VM in order to make logging work with other guest components! 
+
+'''Legacy warning:''' If "LOG_TO_BACKDOOR" is defined you might end up having cluttered logfiles if you use format specifiers (e.g. "%s") in your debug statements. Undefine / delete this define to use the "regular" IPRT way of logging things.
+
+For Shared Folders (Windows: VBoxSF.sys / VBOXMRXNP.dll)
+
+{{{
+VBOX_LOG_FLAGS=thread
+VBOX_LOG=+hgcm.e.f,+shared_folders.e.f
+}}}
+
+Logging settings can be changed at runtime using a debugger.  Here are two examples with gdb:
+
+{{{
+(gdb) call RTLogGroupSettings(0, "+drv_nat.e.l.f.l2.l3")
+$1 = 0
+}}}
+
+is the equivalent of passing the environment variable:
+
+{{{
+VBOX_LOG=+drv_nat.e.l.f.l2.l3
+}}}
+
+and
+
+{{{
+(gdb) call RTLogRelDefaultInstance()
+$1 = (RTLOGGER *) 0x2be2c30
+(gdb) call RTLogFlags(0x2be2c30, "thread")
+$2 = 0
+}}}
+
+is the equivalent of:
+
+{{{
+VBOX_RELEASE_LOG_FLAGS=thread
+}}}