src/vnet/syslog/sylog_doc.md

   1 # Syslog protocol support {#syslog_doc}
   2
   3 VPP provides [RFC5424](https://tools.ietf.org/html/rfc5424) syslog protocol
   4 logging, which is used to transport event messages across network. VPP
   5 currently suports UDP transport based on
   6 [RFC5426](https://tools.ietf.org/html/rfc5426).
   7
   8 The syslog message has the following format:
   9 * header
  10 * structured data
  11 * free-form message
  12
  13 The header contains, priority, version, timestamp, hostname, application,
  14 process id and message id. It is followed by structured data, which  provides
  15 a mechanism to express event data in easily parsable format. Structured data
  16 can contain zero, one or multiple structured data elements. Structured data
  17 element contains name-value pairs. Structured data can by followed by free-form
  18 message.
  19
  20 Following example explains how to use the internal APIs to genrate syslog
  21 message:
  22 ```{.c}
  23    #include <vnet/syslog/syslog.h>
  24
  25    ...
  26
  27    syslog_msg_t syslog_msg;
  28
  29    /* Check if syslog logging is enabled */
  30    if (!syslog_is_enabled ())
  31      return;
  32
  33    /* Severity filer test */
  34    if (syslog_severity_filter_block (severity))
  35      return;
  36
  37    /* Initialize syslog message header */
  38    syslog_msg_init (&syslog_msg, facility, severity, "NAT", "SADD");
  39
  40    /* Create structured data element */
  41    syslog_msg_sd_init (&syslog_msg, "nsess");
  42    /* Add structured data element parameters (name-value pairs) */
  43    syslog_msg_add_sd_param (&syslog_msg, "SSUBIX", "%d", ssubix);
  44    syslog_msg_add_sd_param (&syslog_msg, "SVLAN", "%d", svlan);
  45    syslog_msg_add_sd_param (&syslog_msg, "IATYP", "IPv4");
  46    syslog_msg_add_sd_param (&syslog_msg, "ISADDR", "%U",
  47                             format_ip4_address, isaddr);
  48    syslog_msg_add_sd_param (&syslog_msg, "ISPORT", "%d", isport);
  49    syslog_msg_add_sd_param (&syslog_msg, "XATYP", "IPv4");
  50    syslog_msg_add_sd_param (&syslog_msg, "XSADDR", "%U",
  51                             format_ip4_address, xsaddr);
  52    syslog_msg_add_sd_param (&syslog_msg, "XSPORT", "%d", xsport);
  53    syslog_msg_add_sd_param (&syslog_msg, "PROTO", "%d", proto);
  54
  55    /* Send syslog message */
  56    syslog_msg_send (&syslog_msg);
  57 ```
  58
  59 Example above produces following syslog message:
  60    <134>1 2018-11-12T11:25:30.252715Z 172.16.4.1 NAT 5901 SADD [nsess SSUBIX="0" SVLAN="0" IATYP="IPv4" ISADDR="172.16.1.2" ISPORT="6303" XATYP="IPv4" XSADDR="10.0.0.3" XSPORT="16253" PROTO="6"]
  61
  62 To add free-form message use:
  63 ```{.c}
  64    syslog_msg_add_msg (&syslog_msg, "event log entry");
  65 ```