rsyslog Properties
==================

Data items in rsyslog are called "properties". They can have different
origin. The most important ones are those that stem from received
messages. But there are also others. Whenever you want to access data items,
you need to access the resprective property.

Properties are used in

- :doc:`templates <templates>`
- conditional statements

The property name is case-insensitive (prior to 3.17.0, they were case-senstive).

Message Properties
------------------
These are extracted by rsyslog parsers from the original message. All message
properties start with a letter.

The following message properties exist:

**msg**
  the MSG part of the message (aka "the message" ;))

**rawmsg**
  the message excactly as it was received from the socket. Should be
  useful for debugging. It is also useful if a message should be
  forwarded totally unaltered.

**rawmsg-after-pri**
  Almost the same as **rawmsg**, but the syslog PRI is removed.
  If no PRI was present, **rawmsg-after-pri** is identical to
  **rawmsg**. Note that the syslog PRI is header field that
  contains information on syslog facility and severity. It is
  enclosed in greater-than and less-than characters, e.g.
  "<191>". This field is often not written to log files, but
  usually needs to be present for the receiver to properly
  classify the message. There are some rare cases where one
  wants the raw message, but not the PRI. You can use this
  property to obtain that. In general, you should know that you
  need this format, otherwise stay away from the property.

**hostname**
  hostname from the message

**source**
  alias for HOSTNAME

**fromhost**
  hostname of the system the message was received from (in a relay chain,
  this is the system immediately in front of us and not necessarily the
  original sender). This is a DNS-resolved name, except if that is not
  possible or DNS resolution has been disabled.

**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**
  the "static" part of the tag, as defined by BSD syslogd. For example,
  when TAG is "named[12345]", programname is "named".

**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 brackes (e.g. "local0.err<133>")

**iut**
  the monitorware InfoUnitType - used when talking to a
  `MonitorWare <http://www.monitorware.com>`_ backend (also for
  `Adiscon LogAnalyzer <http://loganalyzer.adiscon.com/>`_)

**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!)

**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 PROTCOL-VERSION field from IETF draft
  draft-ietf-syslog-protcol

**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**
  The name of the input module that generated the message (e.g.
  "imuxsock", "imudp"). Note that not all modules necessarily provide this
  property. If not provided, it is an empty string. Also note that the
  input module may provide any value of its liking. Most importantly, it
  is **not** necessarily the module input name. Internal sources can also
  provide inputnames. Currently, "rsyslogd" is defined as inputname for
  messages internally generated by rsyslogd, for example startup and
  shutdown and error messages. This property is considered useful when
  trying to filter messages based on where they originated - e.g. locally
  generated messages ("rsyslogd", "imuxsock", "imklog") should go to a
  different place than messages generated somewhere.

**jsonmesg**

  *Available since rsyslog 8.3.0*

  The whole message object as JSON representation. Note that the JSON
  string will *not* include and 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 containened 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
-----------------
These properties are provided by the rsyslog core engine. They are **not**
related to the message. All system properties start with a dollar-sign.

For example, ``timereported`` contains the timestamp
from the message. Depending on how long the message was in the relay chain, this
can be quite old. In contrast, ``$now`` is the system time when the message
is being processed. Depending on your needs, you need one or the other. Usually,
the message-based timestamp is the more important one, but that really depdends
on the use case.

The following system properties exist:

**$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.
  
**$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)

**$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 quater hours that are in each hour)

**$minute**
  The current minute (2-digit)

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