documentation/dlog_ctl.txt

   1 dlogctl is a tool which allows developers to control libdlog at runtime.
   2
   3 To use it, runtime control has to be enabled (before the program first calls
   4 the library, as else static configuration is used). You must have a directory
   5 to which all users of the library have read access; put path to this directory
   6 to the `dynamic_config_path` config entry. By default, this is already defined
   7 to `/run/dlog/filters.d`, but you could change it:
   8
   9  $ echo "dynamic_config_path=/my/custom/path.d" >> /etc/dlog.conf
  10
  11 If you're doing this through creating a new file in the config directory,
  12 remember that it also needs to be readable by everyone (common mistake):
  13
  14  $ echo "dynamic_config_path=/my/custom/path.d" > /etc/dlog.conf.d/30-dynamic.conf
  15  $ chsmack -a _ /etc/dlog.conf.d/30-dynamic.conf
  16
  17 Now dynamic control can be exerted. There are two features configurable at
  18 runtime, the first is an extension of the filtering limiter. Of course to
  19 use it, the basic (static) version of the feature has to be enabled as well.
  20 This should already be the case by default, but if not, here's how to:
  21
  22  $ echo "limiter=1" >> /etc/dlog.conf
  23
  24 Another thing to take care of is that for backward-compatiblity reasons,
  25 the limiter used to not apply to the `apps` buffer. This has since changed
  26 but if you have an old config you might also want to change this behaviour:
  27
  28  $ echo "limiter_apply_to_all_buffers=1" >> /etc/dlog.conf
  29
  30 The static config might have already defined some filtering rules.
  31 Let's dump the whole filterset to see what we are working with:
  32
  33  $ dlogctl --get
  34
  35 And some example output:
  36
  37  > Unlimited for *:* (static)
  38  > Denied for FOO:* (static)
  39  >
  40  > Logging buffer status:
  41  > * main: ENABLED
  42  > * radio: DISABLED
  43  > * system: DISABLED
  44  > * apps: ENABLED
  45
  46 In this case we can see that there's a rule to block the FOO tag and no limit
  47 upon other logs; see the filter documentation on what the specific values mean.
  48 Some buffers have also been disabled, more on that later.
  49
  50 Let's say we want to block logs by default; this involves setting the global
  51 filter. Let's also limit the amount of warnings as well. Note, remember that
  52 the asterisk should be under quotes to prevent the shell from expanding it.
  53
  54  $ dlogctl --set deny --tag '*' --priority '*'
  55  $ dlogctl --set 42 --priority 'W'
  56  $ dlogctl --get
  57  > Denied for *:* (dynamic)
  58  > Denied for FOO:* (static)
  59  > 42 logs/minute for *:W (dynamic)
  60  > (buffer status...)
  61
  62 The config has been updated. Now let's see what happens if we want to check
  63 how a specific log with given tag and priority would be filtered:
  64
  65  $ dlogctl --get --tag 'FOO' --priority 'W'
  66  > Nothing set for FOO:W
  67  > Denied for FOO:* (static)
  68  > [shadowed] 42 logs/minute for *:W (dynamic)
  69  > [shadowed] Denied for *:* (dynamic)
  70  > [shadowed] Unlimited for *:* (static)
  71
  72 Note how you can see the precedence of filters, including missing ones. Note
  73 that a static filter can only be overridden by dynamic ones of same or higher
  74 precedence, for example since there is a rule to deny tag FOO, all that can
  75 be done is to either override that or use a tag and priority rule, dynamic
  76 global or priority-only rules won't do anything for FOO logs.
  77 To remove a dynamic rule, use `--set` without a parameter:
  78
  79  $ dlogctl --tag FOO --priority W --set allow
  80  $ dlogctl --priority W --set
  81  $ dlogctl --priority '*' --tag '*' --set
  82  $ dlogctl --tag FOO --priority W --get
  83  > Unlimited for FOO:W (dynamic)
  84  > [shadowed] Nothing set for FOO:W (static)
  85  > [shadowed] Denied for FOO:* (static)
  86  > [shadowed] Nothing set for *:W
  87  > [shadowed] Unlimited for *:* (static)
  88
  89 Earlier we could see that dumping also tells us about buffer status.
  90 This is an override that prevents logs from being sent to a buffer completely.
  91 To enable or disable a buffer, do:
  92
  93  $ dlogctl --enable -b radio -b system
  94  $ dlogctl --disable -b main
  95
  96 Starting from the state in the first example, we'd get:
  97
  98  $ dlogctl --get
  99  > (filters...)
 100  > Logging buffer status:
 101  > * main: DISABLED
 102  > * radio: ENABLED
 103  > * system: ENABLED
 104  > * apps: ENABLED
 105
 106 This is a convenient way to prevent logs from arriving in a buffer completely.
 107 Note that it is not trivial to do this using filters, because setting the
 108 global filter is not enough as it is overridden by specific ones.
 109
 110 Filtering might be familiar to users of dlogutil. However, dlogutil filters
 111 a posteriori while libdlog does a priori. The difference is that libdlog
 112 filtering prevents a log from arriving in the buffer at all, which means it
 113 takes longer for the buffer to start overflowing and deleting old logs,
 114 and spares some processing power which would otherwise be spent on the log.
 115 On the other hand, logs filtered this way are gone forever. Usually it is
 116 still beneficial because most logs are completely worthless but it might be
 117 preferable to avoid it, for example when a program can communicate with
 118 arbitrary other programs.
 119
 120