logging: Improve file & stderr log documentation

Change-Id: I90114f634ae0411e58d2f3da86d5a2e470b4d828
---
M common/chapters/logging.adoc
1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc
index b8365ec..abc5941 100644
--- a/common/chapters/logging.adoc
+++ b/common/chapters/logging.adoc
@@ -288,6 +288,7 @@
 local address, upon creation of the GSMTAP log target, an attempt will be made to create a dummy sink socket
 to avoid such problems automatically.
 
+[[logging_file]]
 ==== Logging to a file
 
 As opposed to Logging to the VTY, logging to files is persistent and
@@ -300,9 +301,10 @@
 ----
 OsmoBSC> enable
 OsmoBSC# configure terminal
-OsmoBSC(config)# log file /path/to/my/file
+OsmoBSC(config)# log file /path/to/my/file <1>
 OsmoBSC(config-log)#
 ----
+<1> Configure a file logging target writing to /path/to/my/file
 
 This leaves you at the config-log prompt, from where you can set the
 detailed configuration for this log file.  The available commands at
@@ -310,6 +312,19 @@
 `logging filter`, `logging level` as well as `logging color`
 and `logging timestamp`.
 
+The file logging target will by default use a synchronous non-blocking I/O
+write. If writing cannot be performed synchronously (would block), the message
+is stored in a workqueue where asynchronous write (driven by poll event loop)
+will be performed at a later stage. The file logging target can be configured
+during the VTY `log file` VTY command to perform blocking I/O with the
+`blocking-io` parameter. This I/O mode should not be used in any osmocom program
+driven by an event loop (which includes any program using a VTY), since it may
+block the thread for an unspecified (potentially long or even infinite) amount
+of time and hence prevent the event loop to run and process events. This I/O
+mode should only be used under specific circumstances, like debugging a crash,
+in which case it's interesting to get the logging output to the UDP socket and
+hence recorded before the program crashes.
+
 TIP: Don't forget to use the `copy running-config startup-config` (or
 its short-hand `write file`) command to make your logging configuration
 persistent across application re-start.
@@ -440,3 +455,7 @@
 OsmoBSC(config)# log stderr
 OsmoBSC(config-log)#
 ----
+
+The stderr logging target can be configured during the VTY `log stderr` VTY
+command to perform blocking I/O with the `blocking-io` parameter. See
+<<logging_file>> for more information.

