Logging: Document the configuration file.

diff --git a/cf/libucw b/cf/libucw
index 4115f6d818e93c5129e781b769f997bb16f264e0..4f0f81b1f7d1d038de87795a0ba04de1d61bd697 100644 (file)
--- a/cf/libucw
+++ b/cf/libucw
@@ -177,33 +177,65 @@ MaxOccurences             4
 
 Logging {
 
-Stream {
-       Name            logfile
-       FileName        log/test
-       Limit { Rate 100 }
-}
-
-Stream {
-       Name            logfile2
-       FileName        log/test2
-       Microseconds    1
-       Levels:reset    info warn error
-       Types:reset     default foo
-       ErrorsFatal     1
-       ShowTypes       1
-}
-
-Stream {
-       Name            syslog
-       SyslogFacility  user
-       SyslogPID       1
-}
-
-Stream {
-       Name            combined
-       Substream       logfile
-       Substream       logfile2
-       Substream       syslog
-}
+# In this section, you can define various logging streams which can be referred to by other sections.
+
+# Stream {
+#      # The name of the stream
+#      Name            test-log
+#
+#      # When it should log the messages to a file, a name of the file should be specified.
+#      # Escape sequences for current date and time as described in strftime(3) can be used.
+#      FileName        log/test-%Y%m%d
+#
+#      # Instead of a file, a syslog facility can be specified. See syslog(3) for an explanation.
+#      SyslogFacility  daemon
+#
+#      # You can request that syslog includes a process ID in each message. Due to inflexibility
+#      # of the syslog protocol, all syslog streams active at a moment must agree on this setting.
+#      # (default: 0)
+#      SyslogPID       1
+#
+#      # When logging to files, timestamps with microsecond precision can be requested. (default: 0)
+#      Microseconds    1
+#
+#      # Messages logged to this stream can be restricted to a subset of severity levels.
+#      # Available levels are: debug info warn error info_r warn_r error_r fatal.
+#      # This configuration item is a bitmap with a default of "all", so we need the ":reset" operator.
+#      Levels:reset    info warn error fatal
+#
+#      # Similarly, messages can be restricted to a subset of message types. The types are
+#      # specific for each program. This configuration item is a list of type names; by default
+#      # it is empty, which is equivalent to all types being enabled.
+#      Types:reset     default foo
+#
+#      # Should the message types be logged? They usually do not carry much useful
+#      # information for the viewer of the log, so they are not included by default,
+#      # but you might want to see them when tuning the Types setting. (default: 0)
+#      ShowTypes       1
+#
+#      # If an error occurs when logging a message to this stream, the program normally
+#      # logs a special error message to the other streams and continues running. You can
+#      # however request to exit the program in such cases, so that the log files are
+#      # guaranteed to be complete. (default: 0)
+#      ErrorsFatal     1
+#
+#      # Some events are logworthy, but they could happen too frequently and flood the log.
+#      # You can avoid the flooding by setting up a rate limiter for a specific subset of
+#      # message types. If more limiters match the type of a message, only the last one applies.
+#      Limit {
+#              # A list of message types (default: empty = all types)
+#              Types           default foo
+#
+#              # The maximum allowed sustained rate (messages/second, may be fractional)
+#              Rate            1
+#
+#              # Maximum length of a burst temporarily exceeding the rate (default: try to guess)
+#              Burst           2
+#      }
+#
+#      # The messages that have passed the filters and limiters can be forwarded to other
+#      # log streams. Logging loops are not healthy for your program :)  (a list of stream names)
+#      Substream       another-stream
+# }
 
 }