7. Structured Data IDs
This document defines three SD-IDs: timeQuality, origin, and meta. Other SD-IDs may be defined by other documents.
7.1. timeQuality
The SD-ID "timeQuality" MAY be used by the originator to describe its notion of system time. This SD-ID SHOULD be written if the originator is not properly synchronized with a reliable external time source or if it does not know whether its time zone offset is correct. This is an indication to the collector or relay that the TIMESTAMP might not be correct.
Parameters in this SD-ID are:
7.1.1. tzKnown
The "tzKnown" parameter MAY be used to indicate whether the originator knows its time zone. It is a PARAM-VALUE containing a single character, either "0" if the time zone information is unknown or "1" if it is known. If this parameter is not present or set to "0", the originator does not know its time zone. If "1", the originator's notion of its time zone offset is contained in the TIMESTAMP.
7.1.2. isSynced
The "isSynced" parameter MAY be used to indicate whether the originator's local clock is synchronized with a reliable time source, e.g., via Network Time Protocol [RFC5905]. It is a PARAM-VALUE containing a single character, either "0" if not synchronized or "1" if synchronized. If this parameter is not present, the originator does not know whether its local clock is synchronized.
7.1.3. syncAccuracy
The "syncAccuracy" parameter MAY be used to indicate the accuracy of the originator's notion of the system time. It is a PARAM-VALUE containing an integer describing the maximum offset from the authoritative time source, in microseconds. A value of "60000000" would indicate a one-minute precision while "2000" indicates 2 milliseconds. This number represents the maximum expected error. It may be derived from knowledge of how often the clock is synchronized. This is OPTIONAL.
If the parameter is not present, the maximum deviation from the authoritative time source is unknown.
7.1.4. Examples
Example 1
[timeQuality tzKnown="1" isSynced="1" syncAccuracy="60000"]
This STRUCTURED-DATA shows that the originator is synchronized with an authoritative time source. The originator believes the time information it provides is accurate within 60 milliseconds. The originator knows its time zone.
Example 2
[timeQuality tzKnown="1" isSynced="0"]
This STRUCTURED-DATA shows that the originator is not synchronized with an authoritative time source. However, it knows its time zone offset.
Example 3
[timeQuality tzKnown="0" isSynced="1" syncAccuracy="60000"]
This STRUCTURED-DATA shows that the originator is synchronized with an authoritative time source, but does not know its time zone offset.
7.2. origin
The SD-ID "origin" MAY be used by an originator, relay, or collector to indicate its identity and enclave boundaries. This SD-ID is meant to be chained, so that each relay or collector that adds it may append its information to the already existing one.
Parameters in this SD-ID are:
7.2.1. ip
The "ip" parameter MAY be used to identify the device that originated the message. The value is a valid IP address in the format described in Section 6.2.4. Anonymized addresses SHOULD NOT be sent, because they do not provide useful troubleshooting information. Doing so may also introduce a conflict with other devices that have been similarly anonymized. If anonymization is required, the message should instead be anonymized at a relay or collector.
7.2.2. enterpriseId
The "enterpriseId" parameter MUST be an "SMI Network Management Private Enterprise Code", maintained by IANA, whose prefix is iso.org.dod.internet.private.enterprise (1.3.6.1.4.1). The number that follows MUST be unique and MUST be registered with IANA as per [RFC5226]. The presence of this parameter serves to identify the type of originator. Originators SHOULD include this parameter.
A relay SHOULD include this parameter if it significantly alters the meaning of the message. In particular, relays that transform messages from a non-syslog protocol into syslog SHOULD include this parameter.
When reading a message with this parameter present, a human user can look up the organization that created the message generator by consulting the registration information for the "SMI Network Management Private Enterprise Codes" at IANA.
7.2.3. software
The "software" parameter is used to identify the software product that generated the message. This SHOULD contain the product name, but MAY contain other information. A relay SHOULD NOT modify this parameter.
7.2.4. swVersion
The "swVersion" parameter is used to identify the version of the software product that generated the message. A relay SHOULD NOT modify this parameter.
7.2.5. Example
[origin ip="192.0.2.1" enterpriseId="32473" software="su" swVersion="1.2.3"]
In this example, the software product that generated the message is identified as "su", version "1.2.3", with the private enterprise number 32473. The device that originated the message has the IP address 192.0.2.1.
7.3. meta
The SD-ID "meta" MAY be used to provide meta-information about the message. This may be used for a variety of purposes, such as quality of service information or in other cases where classifying or enriching the message is desirable.
Parameters in this SD-ID are:
7.3.1. sequenceId
The "sequenceId" parameter SHOULD be used to provide a unique sequence number to identify a message. This sequence number can be used to detect lost messages or to ensure ordering. The sequence ID SHOULD be monotonically increasing. The exact algorithm for this is implementation-specific. This PARAM-VALUE SHOULD be one or more decimal integers. It MAY wrap or start over at the beginning if a sender restarts.
7.3.2. sysUpTime
The "sysUpTime" parameter MAY be used to provide information on how long the system has been up. If the sender restarts, this SHOULD be reset to zero. This may be useful in associating sequences of messages with particular device runs. The value of this parameter is a decimal integer counting the number of seconds since system startup.
7.3.3. language
The "language" parameter is used to specify the language used in the MSG part. This PARAM-VALUE MUST be a language tag as defined by [RFC5646].
If the language of the MSG is not known or cannot be identified, this parameter SHOULD NOT be used.