Changes between Version 3 and Version 4 of Logging

Timestamp:

2012-10-01T15:43:23Z (12 years ago)

Author:

Vojtech Horky

Comment:

Start describing the rewritten logging

Logging

@@ -1 +1 @@
 = Logging functions in HelenOS =
 
-If you want to add logging to your application, you can use already existing functions in `libc`. Currently, the implementation is trivial as the messages are only printed to the screen but using single API allows for further improvements (logging to file/over network etc.).
+If you want to use some kind of logging - either for debugging purposes or
+to report errors - consider using the one provided in `libc`.
+The current implementation does not offer any spectacular features but
+shall be sufficient for most cases.
 
-To use logging functions, include `io/log.h` and initialize the logging subsystem. After that, you can use the `log_msg` to do the logging.
+The logging messages are printed to screen (depending on kernel configuration)
+and are also written to files.
+To prevent flooding of the system with logging messages, the messages
+are assigned severity levels (see table below) and the user specifies how verbose the
+system shall be - i.e. to which detail are the messages actually printed.
+To allow more fine-grained tuning of what-to-print, the messages are
+directed to different logs that form a tree-like structure.
+It is possible to control reporting level (verbosity) of each log separately, giving user
+the ability to exactly specify which part of the system shall be monitored
+in the greatest detail.
+
+For example, a (hypothetical) USB keyboard driver can offer a separate log
+for each keyboard that is plugged in.
+Thus, user trying to find out why his special button does not work can
+specify that ''all'' messages for the special keyboard shall be printed
+but also suppress any other messages - namely from the other keyboard that
+works and which is used to control the system.
+
+Currently, following levels are recognised.
+
+||= Name =||= Typical usage =||
+|| `LVL_FATAL` || Fatal error, program is not able to recover at all. ||
+|| `LVL_ERROR` || Serious error but the program can recover from it.[[BR]]E.g. driver cannot control one device but otherwise is healthy. ||
+|| `LVL_WARN` || Easily recoverable problem, such as one corrupted packet that can be skipped. ||
+|| `LVL_NOTE` || Message that does not indicate a problem, but should be printed at the default logging level. ||
+|| `LVL_DEBUG` || Debugging-purpose message. Not printed at the default logging level. Increasing logging level to LVL_DEBUG should not swamp the log. ||
+|| `LVL_DEBUG2` || More detailed debugging message. ||
+
+
+== Going through existing logs ==
+
+All logs are stored under the `/log/` directory and file name corresponds
+to the server/application where the messages originated.
+To examine these files, one can use `edit` or `cat`.
+
+The file contains the whole tree of the logs - each line is prefixed with
+severity level of the message and name of the log.
+
+'''Example''': running `tester` application with `logger1` test shall
+create a `/log/tester` file with dummy messages.
+The test tries to print message at every severity level, what is
+actually stored into the file depends on current settings (see below for more examples).
+
+
+== Changing reported level at boot time ==
+
+The following currently works only for GRUB-based platforms.
+
+TODO - logger arguments
+
+== Changing reported level at run-time ==
+
+TODO - logset
+
+== Using the C API ==
+
+TODO  log_msg, log_init
+
+
+== Behind the scene
+
+TODO - how logger, logset and log_*() works
+
+
+
+== Obsoleted ==
+
+'''Information below is obsoleted and will be rewritten soon. '''
+
+To use logging functions, include `io/log.h` and initialize the logging
+ subsystem. After that, you can use the `log_msg` to do the logging.
 
 {{{
@@ -24 +97 @@
 }}}
 
-The first argument to `log_init` is application name, the second is the default logging level. Messages with higher level won't be printed at all. Normally the (when an application is not being debugged) the logging level should be set to LVL_NOTE. That is, messages with level LVL_NOTE or higher are printed.
+The first argument to `log_init` is application name, the second is the 
+default logging level. Messages with higher level won't be printed at all.
+ Normally the (when an application is not being debugged) the logging level 
+ should be set to LVL_NOTE. That is, messages with level LVL_NOTE or higher 
+ are printed.
 
-`log_msg` is a `printf`-like function where first argument is level of the message (its seriousness).
+`log_msg` is a `printf`-like function where first argument is level of 
+the message (its seriousness).
 
-Currently, following levels are recognised.
-
-||= Name =||= Typical usage =||
-|| `LVL_FATAL` || Fatal error, program is not able to recover at all. ||
-|| `LVL_ERROR` || Serious error but the program can recover from it.[[BR]]E.g. driver cannot control one device but otherwise is healthy. ||
-|| `LVL_WARN` || Easily recoverable problem, such as one corrupted packet that can be skipped. ||
-|| `LVL_NOTE` || Message that does not indicate a problem, but should be printed at the default logging level. ||
-|| `LVL_DEBUG` || Debugging-purpose message. Not printed at the default logging level. Increasing logging level to LVL_DEBUG should not swamp the log. ||
-|| `LVL_DEBUG2` || More detailed debugging message. ||
-