Fork us on GitHub Follow us on Facebook Follow us on Twitter

Changes between Version 3 and Version 4 of Logging


Ignore:
Timestamp:
2012-10-01T15:43:23Z (7 years ago)
Author:
Vojtech Horky
Comment:

Start describing the rewritten logging

Legend:

Unmodified
Added
Removed
Modified
  • Logging

    v3 v4  
    11= Logging functions in HelenOS =
    22
    3 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.).
     3If you want to use some kind of logging - either for debugging purposes or
     4to report errors - consider using the one provided in `libc`.
     5The current implementation does not offer any spectacular features but
     6shall be sufficient for most cases.
    47
    5 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.
     8The logging messages are printed to screen (depending on kernel configuration)
     9and are also written to files.
     10To prevent flooding of the system with logging messages, the messages
     11are assigned severity levels (see table below) and the user specifies how verbose the
     12system shall be - i.e. to which detail are the messages actually printed.
     13To allow more fine-grained tuning of what-to-print, the messages are
     14directed to different logs that form a tree-like structure.
     15It is possible to control reporting level (verbosity) of each log separately, giving user
     16the ability to exactly specify which part of the system shall be monitored
     17in the greatest detail.
     18
     19For example, a (hypothetical) USB keyboard driver can offer a separate log
     20for each keyboard that is plugged in.
     21Thus, user trying to find out why his special button does not work can
     22specify that ''all'' messages for the special keyboard shall be printed
     23but also suppress any other messages - namely from the other keyboard that
     24works and which is used to control the system.
     25
     26Currently, following levels are recognised.
     27
     28||= Name =||= Typical usage =||
     29|| `LVL_FATAL` || Fatal error, program is not able to recover at all. ||
     30|| `LVL_ERROR` || Serious error but the program can recover from it.[[BR]]E.g. driver cannot control one device but otherwise is healthy. ||
     31|| `LVL_WARN` || Easily recoverable problem, such as one corrupted packet that can be skipped. ||
     32|| `LVL_NOTE` || Message that does not indicate a problem, but should be printed at the default logging level. ||
     33|| `LVL_DEBUG` || Debugging-purpose message. Not printed at the default logging level. Increasing logging level to LVL_DEBUG should not swamp the log. ||
     34|| `LVL_DEBUG2` || More detailed debugging message. ||
     35
     36
     37== Going through existing logs ==
     38
     39All logs are stored under the `/log/` directory and file name corresponds
     40to the server/application where the messages originated.
     41To examine these files, one can use `edit` or `cat`.
     42
     43The file contains the whole tree of the logs - each line is prefixed with
     44severity level of the message and name of the log.
     45
     46'''Example''': running `tester` application with `logger1` test shall
     47create a `/log/tester` file with dummy messages.
     48The test tries to print message at every severity level, what is
     49actually stored into the file depends on current settings (see below for more examples).
     50
     51
     52== Changing reported level at boot time ==
     53
     54The following currently works only for GRUB-based platforms.
     55
     56TODO - logger arguments
     57
     58== Changing reported level at run-time ==
     59
     60TODO - logset
     61
     62== Using the C API ==
     63
     64TODO  log_msg, log_init
     65
     66
     67== Behind the scene
     68
     69TODO - how logger, logset and log_*() works
     70
     71
     72
     73== Obsoleted ==
     74
     75'''Information below is obsoleted and will be rewritten soon. '''
     76
     77To use logging functions, include `io/log.h` and initialize the logging
     78 subsystem. After that, you can use the `log_msg` to do the logging.
    679
    780{{{
     
    2497}}}
    2598
    26 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.
     99The first argument to `log_init` is application name, the second is the
     100default logging level. Messages with higher level won't be printed at all.
     101 Normally the (when an application is not being debugged) the logging level
     102 should be set to LVL_NOTE. That is, messages with level LVL_NOTE or higher
     103 are printed.
    27104
    28 `log_msg` is a `printf`-like function where first argument is level of the message (its seriousness).
     105`log_msg` is a `printf`-like function where first argument is level of
     106the message (its seriousness).
    29107
    30 Currently, following levels are recognised.
    31 
    32 ||= Name =||= Typical usage =||
    33 || `LVL_FATAL` || Fatal error, program is not able to recover at all. ||
    34 || `LVL_ERROR` || Serious error but the program can recover from it.[[BR]]E.g. driver cannot control one device but otherwise is healthy. ||
    35 || `LVL_WARN` || Easily recoverable problem, such as one corrupted packet that can be skipped. ||
    36 || `LVL_NOTE` || Message that does not indicate a problem, but should be printed at the default logging level. ||
    37 || `LVL_DEBUG` || Debugging-purpose message. Not printed at the default logging level. Increasing logging level to LVL_DEBUG should not swamp the log. ||
    38 || `LVL_DEBUG2` || More detailed debugging message. ||
    39