rsyslog学习5 -- Properties属性

Properties

Properties 属性

rsyslog中的数据项称为Properties，有些来源于消息，有些来源于其它

Properties被用于

• 模板
• 条件声明

Properties是大小写敏感的

Properties也有被称为variables，两者意义相同，区别可参考 rsyslog lead author Rainer Gerhards explains the naming difference ，（最初properties是不可变的，但后来引入了可变的properties, 成了variable properties）

消息属性

rsyslog会从原始消息中解析出许多属性，所有的消息属性以字母开始。

msg

the MSG part of the message (aka “the message” ;))

rawmsg

原始消息，一般用来debug或需要原封不动的转发时。需要注意的是 EscapecontrolCharactersOnReceive 默认被启用，这可能会导致转发的消息有所改变

rawmsg-after-pri

移除了PRI的rawmsg。如果本来就没有PRI，那rawmsg-after-pri就等同于rawmsg。PRI是syslog的消息头部中，包含了facility和severity的信息。由 <> 包围，比如<191>。这个字段通常不写入日志，但常用来进行消息分类。

hostname

hostname from the message

source

alias for HOSTNAME

fromhost

消息从认证那接受，对于多个转发的链路，这代表了上一个发送者，而非原始发送者。这是一个DNS解析的名字，除非解析失败或者解析被禁用

fromhost-ip

The same as fromhost, but always as an IP address. Local inputs (like imklog) use 127.0.0.1 in this property.

syslogtag

TAG from the message

programname

BSD syslogd中定义的tag的static部分。比如 “named[12345]”, programname 就是 “named”。

确切的说，programname会被以下字符终结

• end of tag
• nonprintable character
• ‘:’
• ‘[‘
• ‘/’

如果你的程序包含了 ‘/‘，比如 “app/foo[1234]”，那programname就是app，如果是绝对路径比如“/app/foo[1234]”, programname 为空 (“”)。如果确实需要保存 ‘/‘，可以设置全局选项global(parser.permitSlashInProgramName=”on”) 来启用.

Note: this option is available starting at rsyslogd version 8.25.0.

pri

PRI part of the message - undecoded (single value)，数字

pri-text

the PRI part of the message in a textual form with the numerical PRI appended in brackets (e.g. “local0.err<133>”)

iut

the monitorware InfoUnitType - used when talking to a MonitorWare backend (also for Adiscon LogAnalyzer)

syslogfacility

the facility from the message - in numerical form

syslogfacility-text

the facility from the message - in text form

syslogseverity

severity from the message - in numerical form

syslogseverity-text

severity from the message - in text form

syslogpriority

an alias for syslogseverity - included for historical reasons (be careful: it still is the severity, not PRI!)

仍是sererity，不是PRI！！

syslogpriority-text

an alias for syslogseverity-text

timegenerated

timestamp when the message was RECEIVED. Always in high resolution

timereported

timestamp from the message. Resolution depends on what was provided in the message (in most cases, only seconds)

timestamp

alias for timereported

protocol-version

The contents of the PROTOCOL-VERSION field from IETF draft draft-ietf-syslog-protocol

structured-data

The contents of the STRUCTURED-DATA field from IETF draft draft-ietf-syslog-protocol

app-name

The contents of the APP-NAME field from IETF draft draft-ietf-syslog-protocol

procid

The contents of the PROCID field from IETF draft draft-ietf-syslog-protocol

msgid

The contents of the MSGID field from IETF draft draft-ietf-syslog-protocol

inputname

产生消息的imput module名 (e.g. “imuxsock”, “imudp”). 并不是所有的module会提供这个字段，可以留空，名字也可以随意定义，并不一定是真实的module名。

jsonmesg

Available since rsyslog 8.3.0

The whole message object as JSON representation. Note that the JSON string will not include an LF and it will contain all other message properties specified here as respective JSON containers. It also includes all message variables in the “$!” subtree (this may be null if none are present).

This property is primarily meant as an interface to other systems and tools that want access to the full property set (namely external plugins). Note that it contains the same data items potentially multiple times. For example, parts of the syslog tag will by contained in the rawmsg, syslogtag, and programname properties. As such, this property has some additional overhead. Thus, it is suggested to be used only when there is actual need for it.

System Properties

rsyslog引擎产生的properties，和消息本身无关，名字以$开始

注意一些时间相关的系统变量：

• timereported 消息头部中的时间戳，代表消息产生的时间，取决于转发链的长度，这个时间有可能比当前落后很多
• timegenerated 本地系统收到消息的时间。本地rsyslog接受缓存收到的时，在任何处理之前。如果buffer接收了多条消息，那这些消息的 timegenerated都是一样的
• $now is not from the message. 系统开始处理消息的时间。与 timegenerated会有一些差异。 如果消息在队列中长时间等待，那差异可能会达到秒级，甚至小时级。

一些系统属性：

• $bom

  The UTF-8 encoded Unicode byte-order mask (BOM). This may be useful in templates for RFC5424 support, when the character set is know to be Unicode.

• $myhostname

  The name of the current host as it knows itself (probably useful for filtering in a generic way)

Time-Related System Properties

以下这些系统属性存在于本地时间变量中（$now）和 UTC（￥now-utc）中。utc相关的变量都以“-utc” 结尾。在一个模板中，本地时间和UTC只能取其一。

不同的模板在使用 $now时，可能会产生不同的结果，为了避免这种情况，建议使用 timegenerated 。

• $now

  The current date stamp in the format YYYY-MM-DD

• $year

  The current year (4-digit)

• $month

  The current month (2-digit)

• $day

  The current day of the month (2-digit)

• $wday

  The current week day as defined by ‘gmtime()’. 0=Sunday, …, 6=Saturday

• $hour

  The current hour in military (24 hour) time (2-digit)

• $hhour

  The current half hour we are in. From minute 0 to 29, this is always 0 while from 30 to 59 it is always 1.

• $qhour

  The current quarter hour we are in. Much like $HHOUR, but values range from 0 to 3 (for the four quarter hours that are in each hour)

• $minute

  The current minute (2-digit)

• $now-unixtimestamp

  The current time as a unix timestamp (seconds since epoch). This actually is a monotonically increasing counter and as such can also be used for any other use cases that require such counters. This is an example of how to use it for rate-limiting:

  # Get Unix timestamp of current message
  set $.tnow = $$now-unixtimestamp
  
  # Rate limit info to 5 every 60 seconds
  if ($!severity == 6 and $!facility == 17) then {
    if (($.tnow - $/trate) > 60) then {
      # 5 seconds window expired, allow more messages
      set $/trate = $.tnow;
      set $/ratecount = 0;
    }
    if ($/ratecount > 5) then {
      # discard message
      stop
    } else {
      set $/ratecount = $/ratecount + 1;
    }
  }

  NOTE: by definition, there is no “UTC equivalent” of the $now-unixtimestamp property.