logging: Improve file log documentation

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


git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/43/41843/1

diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc
index 849d7bc..57ffbae 100644
--- a/common/chapters/logging.adoc
+++ b/common/chapters/logging.adoc
@@ -300,9 +300,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 +311,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 un specified (potentially long or event 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 cinrcumstances, 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.

