src/logutil/logutil_doc.h

   1 /**
   2  @defgroup CLI_DLOGUTIL dlogutil usage
   3  @ingroup DLOG_COMMAND_LINE_UTILITIES
   4  @brief Log reading utility
   5  @details dlogutil is a utility that can be utilised to read stored logs.
   6
   7 The most rudimentary way to use it is to run it with no parameters; it then prints all stored logs to the standard output and awaits more.
   8
   9 Parameters exist to change this behaviour:
  10
  11 Parameter       | Description
  12 ----------------|---------------------------------
  13 -s              | Set default filter to *:s (see later for details)
  14 -f filename     | Output to given file instead of stdout
  15 -r kbytes       | Rotate log file every this many kilobytes.
  16 -n files        | Keep this many old rotations
  17 -v              | Set log output format.
  18 -b buffer       | Select another buffer
  19 -c              | Clear the selected buffers
  20 -d              | Exit when no more logs are currently available
  21 -t count        | Similar to -d, except only print this many logs from the end
  22 -g              | Get the size of selected buffers instead of printing logs
  23 -h, --help      | Show help info
  24
  25 Additionally, you can specify filters. Filters go behind the parameters and are used to decide which logs are shown.
  26
  27 Each log line has priority and a tag. Filters are specified in the format TAG[:PRIO]. Only logs with given tags and priorities are shown.
  28
  29 You can specify * as the tag to match anything. Beware: only a single asterisk works that way, asterisk is not otherwise expanded. For example, "T*G" filter will NOT match "TAG", only literal "T*G".
  30
  31 If you don't specify any filter, it defaults to *:I
  32 If you specify just * as the tag, without priority, its priority defaults to D
  33 If you specify any other tag without priority, the priority defaults to V
  34
  35 */
  36
  37 #include <stdbool.h>
  38
  39 #define DEFAULT_WRITE_BUFFER_SIZE 1048576
  40
  41 static void show_help(const char *cmd, bool requested_by_user)
  42 {
  43         static const char *format_str = "Usage: %s [options] [filterspecs]"
  44                 "\noptions include:\n"
  45                 "  -s                Set default filter to silent.\n"
  46                 "                    Like specifying filterspec '*:s'\n"
  47                 "  -f <filename>     Log to file. Default to stdout\n"
  48                 "  -r [<kbytes>]     Rotate log every kB (defaults to: " STRINGIFY(DEFAULT_ROTATE_SIZE_KB) "kB). Requires -f and -n > 0, else no rotation\n"
  49                 "  -n <count>        Sets max number of rotated logs to <count> (defaults to: " STRINGIFY(DEFAULT_ROTATE_NUM_FILES) "). Requires -f and -r > 0, else no rotation\n"
  50                 "  -c                clear (flush) the entire log and exit without printing logs\n"
  51                 "  -d                dump the log and then exit (don't block unless also -m)\n"
  52                 "  -m                only monitor the log (don't dump existing logs unless also -d)\n"
  53                 "  -t <count>        print only the most recent <count> lines (implies -d but doesn't work with -m)\n"
  54                 "  -g                get the size of the log's ring buffer and exit\n"
  55                 "  -b <buffer>       request alternate ring buffers (can use multiple)\n"
  56                 "                    ('main', 'radio', 'system', 'apps', 'kmsg', 'syslog')\n"
  57                 "                    the default set is main + system + apps\n"
  58                 "  -u <size>         Sets the size of sort buffer (0 to disable sorting)\n"
  59                 "                    Smaller is faster but lowers sorting quality\n"
  60                 "  -e <size>         Sets the size of the write buffer (0 to disable buffering)\n"
  61                 "                    Larger decreases the amount of writes in exchange for larger memory usage\n"
  62                 "                    and getting logs later (especially in continuous and monitor modes!)\n"
  63                 "                    Default is " STRINGIFY(DEFAULT_WRITE_BUFFER_SIZE) " in the dump mode and 0 otherwise\n"
  64                 "  --pid <pid>       Filter messages by process id\n"
  65                 "  --tid <tid>       Filter messages by thread id\n"
  66                 "  --color <when>    Toggle color coding of headers (when can be 'always', 'auto' or 'never').\n"
  67                 "                    'auto' will only enable colors when writing to a TTY and is the default\n"
  68                 "  --sort-by         Choose a timestamp to sort on. This is advisory, as the timestamp may be missing.\n"
  69                 "                    ('default', 'recv_real', 'recv_mono', 'sent_real', 'sent_mono')\n"
  70                 "                    'default' results in using the normal log order: if possible,\n"
  71                 "                    the timestamp used by format is used, otherwise the source order as configured in\n"
  72                 "                    the DLog configuration is used\n"
  73                 "  --version         Print DLog version\n"
  74                 "  -h or --help      show this help\n"
  75                 "  -v <format>       Sets the log print format. Formats and how they look:\n"
  76                 "                        brief (default): PRI/TAG(PID): MSG\n"
  77                 "                        long: [TIME_SENT_DATE PRI/TAG PID TID]\n"
  78                 "                              MSG\n"
  79                 "                        rwtime: TIME_RECV_DATE [TIME_SENT_NUMERIC_PRECISE] PRI/TAG(PID, TID): MSG\n"
  80                 "                        recv_realtime: TIME_RECV_DATE_PRECISE PRI/TAG(PID, TID): MSG\n"
  81                 "                        kerneltime: TIME_SENT_NUMERIC_PRECISE PRI/TAG(PID, TID): MSG\n"
  82                 "                        threadtime: TIME_SENT_DATE_PRECISE_TIMEZONE PRI/TAG(PID, TID): MSG\n"
  83                 "                        time: TIME_SENT_DATE_PRECISE_TIMEZONE PRI/TAG(PID): MSG\n"
  84                 "                        raw: MSG\n"
  85                 "                        thread: PRI(PID, TID) MSG\n"
  86                 "                        process: PRI(PID) MSG (TAG)\n"
  87                 "                        tag: PRI/TAG: MSG\n"
  88                 "                    And the meanings of the symbols:\n"
  89                 "                        PRI: priority character (VDIWEFS, see below)\n"
  90                 "                        TAG: log tag, usually denotes sending program\n"
  91                 "                        PID: process ID, prefix 'P' when alongside TID\n"
  92                 "                        TID: thread ID, prefix 'T' when alongside PID\n"
  93                 "                        TIME: timestamp, with the following variants:\n"
  94                 "                          DATE: shown as date (eg 12-31 23:59:59)\n"
  95                 "                          NUMERIC: shown as raw integer\n"
  96                 "                          SENT: when the log was sent by app\n"
  97                 "                          RECV: when the log was received by dlog\n"
  98                 "                          PRECISE: extra precision to milliseconds\n"
  99                 "                          TIMZEONE: also shows timezone\n"
 100                 "                    IMPORTANT: logs are sorted by their SENT timestamp\n"
 101                 "                    so choosing a format that shows the RECV timestamp\n"
 102                 "                    means they can appear out of order. Also, some logs\n"
 103                 "                    supply their timestamp in seconds since system boot,\n"
 104                 "                    in which case using a DATE timestamp does not make\n"
 105                 "                    much sense (usually shows dates in January 1970).\n"
 106                 "                    The most reliable choices are 'rwtime' and 'recv_realtime',\n"
 107                 "                    but the default is 'brief' for legacy reasons.\n"
 108                 "                    Additionally, a 'json' format is supported, in which\n"
 109                 "                    each log becomes a line with a JSON object containing\n"
 110                 "                    the following fields: 'priority' (string), 'tid' (number),\n"
 111                 "                    'pid' (number), 'recv_real' (string), 'recv_mono' (number),\n"
 112                 "                    'sent_real' (string), 'sent_mono' (number), 'tag' (string)\n"
 113                 "                    and 'msg' (string). Note that some of the timestamps\n"
 114                 "                    can be missing, but at least one will be available.\n"
 115                 "filterspecs are a series of\n<tag>[*][:priority]\n and \n<prefix>*[:=priority]\n"
 116                 "where <tag> is a log component tag\n"
 117                 "<prefix>* matches all log component tags starting with the prefix\n"
 118                 "and * sets global default policy for all tags not matched by other filterspecs \n"
 119                 "priority is:\n"
 120                 "  V    Verbose - matches all priorities\n"
 121                 "  D    Debug   - matches priorities higher or equal to Debug\n"
 122                 "  I    Info    - matches priorities higher or equal to Info\n"
 123                 "  W    Warn    - matches priorities higher or equal to Warn\n"
 124                 "  E    Error   - matches priorities higher or equal to Error\n"
 125                 "  F    Fatal   - matches priorities equal to Fatal\n"
 126                 "  S    Silent  - does not match any priority - supress output\n"
 127                 "\n =<priority> - matches exactly specified policy, for example:\n"
 128                 " =W matches only Warn priority\n"
 129                 "\n'*' means '*:D' and <tag> by itself means <tag>:V\n"
 130                 "If no filterspec is found, filter defaults to '*:D'\n\n";
 131
 132         if (requested_by_user)
 133                 printf(format_str, cmd);
 134         else
 135                 ERR(format_str, cmd);
 136 }