doc/logflagsenv.txt

   1 HEAD~ Controlling what gets logged; NOBUG_ENV; environment variable for loging control
   2
   3 The `NOBUG_INIT_FLAG...` series of macros parse the environment variable
   4 '$NOBUG_LOG'. This enviromnet variable iis thus used to configure what is
   5 logged at runtime. Its syntax is as following:
   6
   7 [source,prolog]
   8 ----
   9 logdecl_list --> logdecl, any( ',' logdecl_list).
  10
  11 logdecl --> flag, opt(limitdecl, any(targetdecl)).
  12
  13 flag --> "identifier of a flag".
  14
  15 limitdecl --> ':', "LIMITNAME".
  16
  17 targetdecl --> '@', "targetname", opt(targetopts).
  18
  19 targetopts --> '(', "options for target", ')', opt(targetopts).
  20 ----
  21
  22 Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations for
  23 flags, which is the name of the flag followed by a limit which is all written in
  24 uppercase letters and preceeded by a colon, followed by target declarations
  25 which are the names of targets, introduced by an at sign. Target declarations
  26 can have options, which are described in the next section. Limit and target
  27 declarations are optional and defaults are selected from the table above. The
  28 defaults presented here are currently an approximation of what might be viable.
  29 The default values used here may be redefined in a future release.
  30
  31 HEAD^ Targets and Options; logging options; configure what gets logged
  32
  33 The Following options are available:
  34
  35 `@ringbuffer`::
  36   `(file=`'filename'`)`:::
  37     set 'filename' for the backing ringbuffer
  38   `(size=`'nnn'`)`:::
  39     set size of the ringbuffer to 'nnn' bytes, rounded-off up to the next page
  40     boudary
  41   `(append)`:::
  42     don't erase existing ringbuffer, start where it left off
  43   `(keep)`:::
  44     keep file after application ends
  45   `(temp)`:::
  46     unlink file instantly at creation
  47
  48 The default ringbuffer is a temporary file in `/tmp` with the `temp` option.
  49 This means it will not be accessible.
  50
  51
  52 `@console`::
  53   `(fd=`'n'`)`:::
  54     redirect console output to fd 'n'
  55
  56 When running under a debugger, NoBug tries to use debugger facilities
  57 to print console messages.
  58
  59 `@file`::
  60   `(name=`'filename'`)`:::
  61     log to 'filename'
  62   `(append)`:::
  63     append to (existing) logfile
  64
  65 `@syslog`::
  66   `(ident=`'name'`)`:::
  67     global prefix for syslog
  68   `(cons)`:::
  69     log to system console if syslog is down
  70   `(pid)`:::
  71     include the process identifier in the log
  72   `(perror)`:::
  73     log to stderr as well (Not available on all systems)
  74
  75
  76 .How $NOBUG_LOG is used
  77 [source,sh]
  78 ----
  79 # set limit to the default target and default limit
  80 # (see table above)
  81 NOBUG_LOG='flag,other'
  82
  83 # set the limit of the default target to DEBUG
  84 NOBUG_LOG='flag:DEBUG'
  85
  86 # set console and syslog limits for flag to DEBUG
  87 NOBUG_LOG='flag:DEBUG@console@syslog'
  88
  89 # trace 'other' to a persistent ringbuffer
  90 NOBUG_LOG=\
  91  'other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
  92 ----