doc/user/extlog.rst

   1 .. _ext-log-target:
   2
   3 ***********************
   4 Extended Logging Target
   5 ***********************
   6
   7 After creating one or more extended logging targets with the
   8 :clicmd:`log extended EXTLOGNAME` command, the target(s) must be configured
   9 for the desired logging output.
  10
  11 Each extended log target supports emitting log messages in one of the following
  12 formats:
  13
  14 - ``rfc5424`` - :rfc:`5424` - modern syslog with ISO 8601 timestamps, time zone and
  15   structured data (key/value pairs) support
  16 - ``rfc3164`` - :rfc:`3164` - legacy BSD syslog, timestamps with 1 second granularity
  17 - ``local-syslog`` - same as :rfc:`3164`, but without the hostname field
  18 - ``journald`` - systemd's `native journald protocol <https://systemd.io/JOURNAL_NATIVE_PROTOCOL/>`_.
  19   This protocol also supports structured data (key/value pairs).
  20
  21 Destinations
  22 ------------
  23
  24 The output location is configured with the following subcommands:
  25
  26 .. clicmd:: destination none
  27
  28    Disable the target while retaining its remaining configuration.
  29
  30 .. clicmd:: destination syslog [supports-rfc5424]
  31
  32    Send log messages to the system's standard log destination
  33    (``/dev/log``).  This does not use the C library's ``syslog()`` function,
  34    instead writing directly to ``/dev/log``.
  35
  36    On NetBSD and FreeBSD, the RFC5424 format is automatically used when
  37    the OS version is recent enough (5.0 for NetBSD, 12.0 for FreeBSD).
  38    Unfortunately, support for this format cannot be autodetected otherwise,
  39    and particularly on Linux systems must be enabled manually.
  40
  41 .. clicmd:: destination journald
  42
  43    Send log messages to systemd's journald.
  44
  45 .. clicmd:: destination <stdout|stderr|fd <(0-63)|envvar WORD>> \
  46                 [format FORMAT]
  47
  48    Send log messages to one of the daemon's file descriptors.  The
  49    ``fd (0-63)`` and ``fd envvar WORD`` variants are intended to work with
  50    the shell's ``command 3>something`` and bash's
  51    ``command {ENVVAR}>something`` I/O redirection specifiers.
  52
  53    Only file descriptors open at a daemon's startup time can be used for
  54    this;  accidental misuse of a file descriptor that has been opened by
  55    FRR itself is prevented.
  56
  57    Using FIFOs with this option will work but is unsupported and can cause
  58    daemons to hang or crash depending on reader behavior.
  59
  60    Format defaults to RFC5424 if none is specified.
  61
  62    .. note::
  63
  64       When starting FRR daemons from custom shell scripts, make sure not
  65       to leak / leave extraneous file descriptors open.  FRR daemons do not
  66       close these.
  67
  68 .. clicmd:: destination file PATH \
  69                 [create [{user WORD|group WORD|mode PERMS}]|no-create] \
  70                 [format FORMAT]
  71
  72    Log to a regular file.  File permissions can be specified when FRR creates
  73    the file itself.
  74
  75    Format defaults to RFC5424 if none is specified.
  76
  77    .. note::
  78
  79       FRR will never change permissions or ownership on an existing log file.
  80       In many cases, FRR will also not have permissions to set user and group
  81       arbitrarily.
  82
  83 .. clicmd:: destination unix PATH [format FORMAT]
  84
  85    Connect to a UNIX domain socket and send log messages there.  This will
  86    autodetect ``SOCK_STREAM``, ``SOCK_SEQPACKET`` and ``SOCK_DGRAM`` and
  87    adjust behavior appropriately.
  88
  89 Options
  90 -------
  91
  92 .. clicmd:: priority PRIORITY
  93
  94    Select minimum priority of messages to send to this target.  Defaults to
  95    `debugging`.
  96
  97 .. clicmd:: facility FACILITY
  98
  99    Select syslog facility for messages on this target.  Defaults to `daemon`.
 100    The :clicmd:`log facility [FACILITY]` command does not affect extended
 101    targets.
 102
 103 .. clicmd:: timestamp precision (0-9)
 104
 105    Set desired number of sub-second timestamp digits.  This only has an effect
 106    for RFC5424 and journald format targets;  the RFC3164 and local-syslogd
 107    formats do not support any sub-second digits.
 108
 109 .. clicmd:: timestamp local-time
 110
 111    Use the local system timezone for timestamps rather than UTC (the default.)
 112
 113    RFC5424 and journald formats include zone information (``Z`` or ``+-NN:NN``
 114    suffix in ISO8601).  RFC3164 and local-syslogd offer no way of identifying
 115    the time zone used, care must be taken that this option and the receiver
 116    are configured identically, or the timestamp is replaced at the receiver.
 117
 118    .. note::
 119
 120       FRR includes a timestamp in journald messages, but journald always
 121       provides its own timestamp.
 122
 123 .. clicmd:: structured-data <code-location|version|unique-id|error-category|format-args>
 124
 125    Select additional key/value data to be included for the RFC5424 and journald
 126    formats.  Refer to the next section for details.
 127
 128    ``unique-id`` and ``error-category`` are enabled by default.
 129
 130    .. warning::
 131
 132       Log messages can grow in size significantly when enabling additional
 133       data.
 134
 135
 136 Structured data
 137 ---------------
 138
 139 When using the RFC5424 or journald formats, FRR can provide additional metadata
 140 for log messages as key/value pairs.  The following information can be added
 141 in this way:
 142
 143 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 144 | Switch             | 5424 group         | 5424 item(s) | journald field   | Contents                                    |
 145 +====================+====================+==============+==================+=============================================+
 146 | always active      | ``location@50145`` | ``tid``      | ``TID``          | Thread ID                                   |
 147 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 148 | always active      | ``location@50145`` | ``instance`` | ``FRR_INSTANCE`` | Multi-instance number                       |
 149 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 150 | ``unique-id``      | ``location@50145`` | ``id``       | ``FRR_ID``       | ``XXXXX-XXXXX`` unique message identifier   |
 151 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 152 | ``error-category`` | ``location@50145`` | ``ec``       | ``FRR_EC``       | Integer error category number               |
 153 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 154 | ``code-location``  | ``location@50145`` | ``file``     | ``CODE_FILE``    | Source code file name                       |
 155 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 156 | ``code-location``  | ``location@50145`` | ``line``     | ``CODE_LINE``    | Source code line number                     |
 157 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 158 | ``code-location``  | ``location@50145`` | ``func``     | ``CODE_FUNC``    | Source code function name                   |
 159 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 160 | ``format-args``    | ``args@50145``     | ``argN``     | ``FRR_ARGn``     | Message printf format arguments (n = 1..16) |
 161 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 162 | ``version``        | ``origin``         | multiple     | n/a              | FRR version information (IETF format)       |
 163 +--------------------+--------------------+--------------+------------------+---------------------------------------------+
 164
 165 The information added by ``version`` is
 166 ``[origin enterpriseId="50145" software="FRRouting" swVersion="..."]``
 167 and is the same for all log messages.  (Hence makes little sense to include in
 168 most scenarios.)  50145 is the FRRouting IANA Enterprise Number.
 169
 170 Crashlogs / backtraces do not include any additional information since it
 171 cannot safely be retrieved from a crash handler.  However, all of the above
 172 destinations will deliver crashlogs.
 173
 174
 175 Restart and Reconfiguration caveats
 176 -----------------------------------
 177
 178 FRR uses "add-delete" semantics when reconfiguring log targets of any type
 179 (including both extended targets mentioned here as well as the global
 180 :clicmd:`log stdout LEVEL` and :clicmd:`log syslog [LEVEL]` variants.)  This
 181 means that when changing logging configuration, log messages from threads
 182 executing in parallel may be duplicated for a brief window of time.
 183
 184 For the ``unix``, ``syslog`` and ``journald`` extended destinations, messages
 185 can be lost when the receiver is restarted without the use of socket
 186 activation (i.e. keeping the receiver socket open.)  FRR does not buffer
 187 log messages for later delivery, meaning anything logged while the receiver
 188 is unavailable is lost.  Since systemd provides socket activation for
 189 journald, no messages will be lost on the ``journald`` target.