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 is 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
  23 for flags, which is the name of the flag followed by a limit which is all
  24 written in uppercase letters and preceeded by a colon, followed by target
  25 declarations which are the names of targets, introduced by an at sign. Target
  26 declarations can have options, which are described in the next section. Limit
  27 and target declarations are optional and defaults are selected from the
  28 xref:loggingleveldefaults[table above]. The defaults presented here are
  29 currently an approximation of what might be viable. The default values used
  30 here may be redefined in a future release.
  31
  32 HEAD^ Targets and Options; loggingoptions; configure what gets logged
  33
  34 The Following options are available:
  35
  36 `@ringbuffer`::
  37   `(file=`'filename'`)`:::
  38     set 'filename' for the backing ringbuffer
  39   `(size=`'nnn'`)`:::
  40     set size of the ringbuffer to 'nnn' bytes, rounded-off up to the next page
  41     boudary
  42   `(append)`:::
  43     don't erase existing ringbuffer, start where it left off
  44   `(keep)`:::
  45     keep file after application ends
  46   `(temp)`:::
  47     unlink file instantly at creation
  48
  49 The default ringbuffer is a temporary file in '/tmp' with the `temp` option.
  50 This means it will not be available and accessible for inspection, but it also
  51 won't leave any stale data behind when the application ends.
  52
  53
  54 `@console`::
  55   `(fd=`'n'`)`:::
  56     redirect console output to fd 'n'
  57
  58 When running under a debugger, NoBug tries to use debugger facilities
  59 to print console messages.
  60
  61 `@file`::
  62   `(name=`'filename'`)`:::
  63     log to 'filename'
  64   `(append)`:::
  65     append to (existing) logfile
  66
  67 `@syslog`::
  68   `(ident=`'name'`)`:::
  69     global prefix for syslog
  70   `(cons)`:::
  71     log to system console if syslog is down
  72   `(pid)`:::
  73     include the process identifier in the log
  74   `(perror)`:::
  75     log to stderr as well (Not available on all systems)
  76
  77
  78 .How $NOBUG_LOG is used
  79 [source,sh]
  80 ----
  81 # set limit to the default target and default limit
  82 # (see table above)
  83 NOBUG_LOG='flag,other'
  84
  85 # set the limit of the default target to DEBUG
  86 NOBUG_LOG='flag:DEBUG'
  87
  88 # set console and syslog limits for flag to DEBUG
  89 NOBUG_LOG='flag:DEBUG@console@syslog'
  90
  91 # trace 'other' to a persistent ringbuffer
  92 NOBUG_LOG=\
  93  'other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
  94 ----