Zum Hauptinhalt springen

Appendix A. Implementer Guidelines

This appendix provides non-normative guidance for implementers of the syslog protocol.

A.1. Relationship with BSD Syslog​

RFC 3164 described the BSD syslog protocol, which has been widely deployed for many years. This document obsoletes RFC 3164 but maintains significant compatibility.

Key differences:

  • VERSION field: This specification adds an explicit VERSION field. Legacy implementations will not recognize this field.

  • TIMESTAMP format: This specification uses RFC 3339 timestamps with full date, time zone, and optional fractional seconds. RFC 3164 used a simpler format without year or time zone.

  • STRUCTURED-DATA: This specification introduces structured data elements. RFC 3164 had no equivalent mechanism.

  • MSG format: The TAG field from RFC 3164 has been split into APP-NAME, PROCID, and MSGID fields in the HEADER.

Interoperability considerations:

When communicating with RFC 3164 systems:

  • Sending to legacy systems: Format messages according to RFC 3164 if the receiver does not support this specification. The transport sender should detect receiver capabilities or allow configuration.

  • Receiving from legacy systems: Receivers compliant with this specification should be able to parse RFC 3164 messages. The receiver may transform them into the format defined in this document.

  • Relay behavior: Relays may need to transform messages between formats. When converting from this specification to RFC 3164:

    • Remove VERSION field
    • Convert TIMESTAMP to MMM DD HH:MM:SS format
    • Drop time zone and year information
    • Remove STRUCTURED-DATA or append to MSG
    • Reconstruct TAG from APP-NAME and PROCID

  • Converting RFC 3164 to this specification:

    • Set VERSION to 1
    • Add current year to timestamp
    • Use relay's time zone or UTC
    • Parse TAG into APP-NAME and PROCID (best effort)
    • Set MSGID to NILVALUE if not determinable

A.2. Message Length​

The minimum required receiver capacity of 480 octets has practical implications:

Why 480 octets?

  • Single UDP packet without fragmentation on many networks
  • Higher likelihood of delivery in degraded networks
  • Compatibility with limited implementations

Implications:

  • Critical messages: Security alerts and operational emergencies should fit within 480 octets
  • Troubleshooting data: Keep diagnostic messages compact
  • Important data first: Place critical information early in the message

Larger messages:

Many modern deployments support much larger messages:

  • TLS transport typically allows tens or hundreds of kilobytes
  • TCP transport has no practical size limit
  • Modern implementations often support 2048, 8192, or larger messages

Best practices:

  • Configure maximum message sizes based on deployment requirements
  • Use STRUCTURED-DATA for important metadata (counted in message length)
  • Test maximum message sizes in your environment
  • Implement graceful handling of oversized messages (truncation or rejection)
  • Monitor for truncated messages at collectors

UTF-8 considerations:

Message length is measured in octets, not characters. A 1000-character UTF-8 string may be 3000 or more octets if it contains non-ASCII characters. Implementers must account for this when sizing messages.

A.3. Severity Values​

Proper use of Severity values improves message utility.

Guidelines:

  • Emergency (0): Use sparingly for true emergencies

    • System is completely unusable
    • Imminent failure of critical hardware
    • Data loss is occurring

  • Alert (1): Immediate action required

    • Service outage
    • Security breach detected
    • Critical resource exhaustion imminent

  • Critical (2): Critical conditions

    • Hard drive failure
    • Primary network connection lost
    • Application crashes

  • Error (3): Error conditions

    • Non-critical service failures
    • Recoverable errors
    • Connection timeouts

  • Warning (4): Warning conditions

    • Resource usage approaching limits
    • Deprecated feature usage
    • Configuration issues

  • Notice (5): Normal but significant

    • Service start/stop
    • Configuration changes
    • Security-relevant normal events

  • Informational (6): Informational messages

    • Routine operations
    • Status messages
    • Connection establishment

  • Debug (7): Debug-level messages

    • Detailed diagnostic information
    • Developer-oriented messages
    • Should be disabled in production

Configuration considerations:

Allow administrators to:

  • Adjust severity assignments per deployment needs
  • Filter messages by severity
  • Route severities to different collectors
  • Override severity for specific message types

Avoid severity abuse:

  • Don't mark all messages as Emergency
  • Don't use Debug severity for production events
  • Consider operator alert fatigue

A.4. TIME-SECFRAC Precision​

The TIMESTAMP field supports fractional seconds up to 6 digits (microseconds).

Common mistakes:

Dropping leading zeros:

WRONG: 2003-10-11T22:13:14.3      (appears to be 300ms)
RIGHT: 2003-10-11T22:13:14.003    (actually 3ms)

Precision recommendations:

  • Use milliseconds (3 digits) for most applications
  • Use microseconds (6 digits) for high-precision timing
  • Omit fractional seconds if sub-second precision is not needed
  • Ensure time synchronization (NTP) supports required precision

Implementation notes:

Not all systems can provide microsecond precision. It is acceptable to:

  • Provide less precision than 6 digits
  • Round or truncate to available precision
  • Omit TIME-SECFRAC entirely if precision is not available

A.5. Case Convention for Names​

This document uses "lower camel case" for SD-IDs and PARAM-NAMEs.

Convention:

  • First letter lowercase
  • Subsequent word first letters uppercase
  • No hyphens or underscores

Examples:

  • timeQuality
  • syncAccuracy
  • enterpriseId
  • myCompanyName

Benefits:

  • Consistency across implementations
  • Readability
  • Compatibility with various programming languages

Recommendations:

Use this convention for:

  • New SD-IDs
  • PARAM-NAMEs
  • Extension identifiers

Private implementations may use other conventions but consistency is recommended.

A.6. Syslog Applications Without Knowledge of Time​

Section 6.2.3 allows NILVALUE for TIMESTAMP when time is unknown.

When to use NILVALUE for TIMESTAMP:

  • Embedded systems without real-time clocks
  • Boot-time messages before time sync
  • Systems where time retrieval has failed

When NOT to use NILVALUE:

  • When the OS provides time functions
  • When lazy implementation wants to avoid time handling
  • When time is available but inconvenient to obtain

Best practices:

  • Emit valid TIMESTAMPs whenever possible
  • Use NILVALUE only when truly impossible to obtain time
  • Consider time zone vs accuracy tradeoffs
  • Document time handling in your implementation

Relay handling:

Relays receiving messages with NILVALUE TIMESTAMP may:

  • Forward as-is
  • Replace with relay's current time
  • Drop messages (if policy requires timestamps)

Configuration should control this behavior.

A.7. Notes on the timeQuality SD-ID​

The timeQuality SD-ID provides valuable metadata about timestamp accuracy.

tzKnown parameter:

Default should be 0 (unknown) unless:

  • Administrator has explicitly configured time zone
  • OS provides reliable time zone information
  • System has validated time zone against external source

isSynced parameter:

Set to 1 only when:

  • NTP or other time sync is active
  • Synchronization is verified successful
  • Time source is trusted

syncAccuracy parameter:

Only provide when:

  • Actual accuracy is known (from NTP statistics)
  • Administrator has configured expected accuracy
  • Measurement data supports the claim

Do not overstate accuracy:

False precision damages trust in logs. It is better to:

  • Omit timeQuality entirely if uncertain
  • Provide conservative accuracy estimates
  • Document accuracy claims

A.8. UTF-8 Encoding and the BOM​

The BOM (Byte Order Mark) signals UTF-8 encoding in the MSG field.

BOM details:

  • Byte sequence: 0xEF 0xBB 0xBF
  • Appears at start of MSG field
  • Indicates UTF-8 encoding follows

When to include BOM:

  • When MSG contains UTF-8 encoded text
  • When certainty of UTF-8 encoding exists
  • For consistency with organization policy

When to omit BOM:

  • When MSG encoding is unknown or uncertain
  • When MSG contains binary data
  • For backward compatibility with systems that don't handle BOM

Receiver handling:

Receivers should:

  • Detect BOM presence
  • Process UTF-8 accordingly
  • Handle messages without BOM (assume unknown encoding)
  • Not display BOM to end users

Relay handling:

Relays forwarding messages should:

  • Preserve BOM if present
  • Not add BOM unless transcoding to UTF-8
  • Not remove BOM unless transcoding to another encoding