Appendix A. Implementer Guidelines
A.1. Relationship with BSD Syslog
This document is a successor to [RFC3164]. The format of the message has been changed from the BSD syslog format to use structured data and a clearly defined message format. This appendix describes some of the differences and backward compatibility concerns.
The most obvious difference is that [RFC3164] did not formalize the syslog message format. While [RFC3164] described a packet format, it was based on observations of existing implementations. Over time, implementations have evolved in different directions. This specification is written so that devices following this format can interoperate properly. At the same time, the format has been designed to coexist with older BSD syslog senders and receivers.
The HEADER format described in Section 6.2 starts with the PRI field, followed by the VERSION field. The PRI field is formatted in the same way as in [RFC3164]. The VERSION field enables new implementations to identify messages formatted according to this specification. It also provides some limited backward compatibility with [RFC3164]. A receiver implementing [RFC3164] would likely interpret the VERSION character as the first character of the HOSTNAME field. This may or may not be desired behavior.
The TIMESTAMP field may use the NILVALUE. This differs from [RFC3164], which specified that a missing TIMESTAMP was to be inferred from the reception time. However, a NILVALUE in the TIMESTAMP field explicitly indicates that time is not available.
Messages conforming to this specification can be distinguished from messages conforming to [RFC3164] because the latter do not contain a VERSION field immediately following the PRI field.
A.2. Message Length
There has been significant confusion about the maximum message length for syslog messages. [RFC3164] states that "The total length of the packet MUST be 1024 bytes or less." This has led to interoperability problems because many implementations accept longer messages, and some implementations that try to honor the 1024-byte length have had to truncate messages.
This document does not impose a maximum message length. Instead, the transport mapping defines the minimum maximum supported message length. A transport receiver is free to accept larger messages. This has led to the definition of a minimum required length of 480 octets. All transport receivers MUST be able to accept messages of this length. Transport receivers SHOULD be able to accept messages of up to and including 2048 octets. If longer messages need to be supported, the transport mapping may define longer minimum maximum lengths.
A.3. Severity Values
The severity values are taken from [RFC3164] and the BSD syslog implementations. There is no standard or universally-accepted mapping from severity values to actual importance. The meanings described in Table 2 are guidelines. Each implementation may have its own definition for each severity level.
In practice, severities are often used for filtering. Operators may wish to receive only messages of high severity levels, or they may wish to store only messages of certain severities. Because of this, message originators SHOULD select appropriate severity levels that make logical sense in the context of their operation.
A.4. TIME-SECFRAC Precision
This document specifies that the TIME-SECFRAC field can have up to 6 digits. This provides microsecond precision. However, there is no requirement that all digits be significant. An originator may provide only 3 digits (millisecond precision) if that is the limit of its clock resolution. Alternatively, an originator might provide all 6 digits but only guarantee that the first 3 are accurate.
The receiver of a message cannot determine the clock accuracy from the TIME-SECFRAC field alone. If clock accuracy information is important, the originator SHOULD include the timeQuality SD-ID (Section 7.1) to provide additional information about its clock.
A.5. Case Convention for Names
SD-ID, PARAM-NAME, APP-NAME, and MSGID are case-sensitive. This means that "eventId" is different from "eventID" and "EventID". This was decided to provide maximum flexibility. However, it also means that care must be taken when defining SD-IDs and PARAM-NAMEs.
There is no required case convention for SD-IDs and PARAM-NAMEs. However, as a guideline, names in camelCase are suggested (e.g., "eventSource", "sequenceId"). This is consistent with common conventions used in many programming languages.
A.6. Syslog Applications Without Knowledge of Time
Some syslog applications may not be able to determine the current time. This might be because the device does not have a time source or because the time source is temporarily unavailable. In such cases, the NILVALUE ("-") MUST be used for the TIMESTAMP field.
When a relay receives a message with a NILVALUE in the TIMESTAMP field, it MAY insert its own timestamp. This would allow the relay to add time information to messages that do not have it. However, the relay SHOULD NOT do this if it would alter the meaning of the message. For example, if the message is describing an event that occurred at a specific time, replacing the NILVALUE with the relay's current time would be inappropriate.
A.7. Notes on the timeQuality SD-ID
The timeQuality SD-ID (Section 7.1) is designed to allow an originator to provide information about the quality of its clock. This information can be useful for log analysis.
For example, if a network device loses connectivity to its NTP server, it might set isSynced="0" to indicate that its clock is no longer being synchronized. If the device's clock drifts significantly while it is not synchronized, any timestamps it produces may be inaccurate. The timeQuality SD-ID allows the device to indicate this situation.
The syncAccuracy parameter is particularly useful for indicating the expected accuracy of the timestamp. This allows log analysis tools to determine whether the time information is accurate enough for correlation purposes.
A.8. UTF-8 Encoding and the BOM
The MSG field may be encoded in UTF-8. If it is encoded in UTF-8, it MUST begin with the UTF-8 byte order mark (BOM), which is the octet sequence %xEF.BB.BF.
The BOM is used as an indicator that the MSG is UTF-8 encoded. If the BOM is present, the receiver SHOULD interpret the MSG as UTF-8. If the BOM is not present, the encoding is not specified by this document.
It is important to note that the BOM is only used at the beginning of the MSG field. It MUST NOT appear anywhere else in the message. If the BOM appears anywhere else, it SHOULD be treated as data, not as a BOM.