doc/logformat.txt

   1 HEAD~ Log Line Format; logformat; format of a log line
   2
   3 Logging follows a rather rigid format and is not configurable. This is
   4 intentional to make it easier to compare and process logs afterwards. NoBug is
   5 designed with the goal to effectively do very fine grained logging and then
   6 analyze this logs later, either manually or with further tools.
   7
   8 A typical log looks like:
   9
  10  0000000003: TRACE: test.c:10: thread_1: main: message
  11  0000000003! TRACE: test.c:10: thread_1: main: continued
  12  0000000005: NOTICE: test.c:15: thread_1: main: next
  13
  14 The components are delimited by ": " or in one case by "! " are as following:
  15
  16  . *Sequence Number* +
  17    Each logging event increments a counter, for preformance (and privacy)
  18    reasons we do not use timestamps here. The sequence number is represented by
  19    ten decimal digits, overflows are not specially handled. There is a special
  20    case that when the final message (see below) spans more log lines, then the
  21    delimiter after the sequence number is a "! " and not ": ". The sequence
  22    numbers in a log can be sparse because not every event is send to the log,
  23    the left out lines are still available in the ringbuffer.
  24
  25  . *NoBug Facility* +
  26    Describes what NoBug macro produced the output. This can be a simple
  27    annotation or logging as well as assertions or one of the more complex
  28    NoBug facilities.
  29
  30  . *File and Linenumber* +
  31    The filename is only printed without it's path. This is important for some
  32    reasons. First it makes the log vastly more readable and second depending
  33    on source location and build system and configuration thereof paths are not
  34    easily reproducible, this makes it hard to use simple tools like grep or
  35    diff on logs generated on different systems. For some messages the filename
  36    and/or the linenumber is not available or meaningless, a "-" is used then.
  37
  38  . *Thread Identifier* +
  39    Shows which thread generated this message. The single threaded version of
  40    NoBug uses always "-".
  41
  42  . *Function Name* +
  43    Gives the function in which the logging occured. For a lot macros it is
  44    possible to pass a context (file, line and function name) around to make it
  45    possible to delegate validation and logging to some special functions while
  46    still being able to present the context where the call originated. NoBug
  47    only uses the function name as identifier here no pretty printed prototype
  48    or demangled C++ method. The reason for this is that neither is well
  49    specified an may yield to non unique results which may even interfere with
  50    the logging format syntax and thus make it very unreliable to write tools
  51    to process logs. Some contexts dont provide a function name, a "-" is used
  52    then.
  53
  54  . *Message* +
  55    The rest of the log line is the user-defined and optional message part.
  56    There are no constraints on the format and one should constrain himself to
  57    print only meaningful textual information. Embedded newlines will always be
  58    translated into a new logging line as shown in the example above.
  59