附录 A. 实施者指南 (Implementer Guidelines)

本附录为 syslog 协议的实施者提供非规范性指导。

A.1. 与 BSD Syslog 的关系

RFC 3164 描述了 BSD syslog 协议,该协议已被广泛部署多年。本文档废弃了 RFC 3164,但保持了重要的兼容性。

主要差异:

VERSION 字段: 本规范添加了明确的 VERSION 字段。旧版实现将无法识别此字段。
TIMESTAMP 格式: 本规范使用带有完整日期、时区和可选秒小数部分的 RFC 3339 时间戳。RFC 3164 使用了更简单的格式,没有年份或时区。
STRUCTURED-DATA: 本规范引入了结构化数据元素。RFC 3164 没有等效机制。
MSG 格式: RFC 3164 的 TAG 字段已拆分为 HEADER 中的 APP-NAME、PROCID 和 MSGID 字段。

互操作性考虑事项:

与 RFC 3164 系统通信时:

发送到旧版系统: 如果接收方不支持本规范,则按照 RFC 3164 格式化消息。传输发送方应检测接收方能力或允许配置。
从旧版系统接收: 符合本规范的接收方应能够解析 RFC 3164 消息。接收方可以将它们转换为本文档中定义的格式。
中继行为: 中继可能需要在格式之间转换消息。从本规范转换到 RFC 3164 时:
- 删除 VERSION 字段
- 将 TIMESTAMP 转换为 MMM DD HH:MM:SS 格式
- 删除时区和年份信息
- 删除 STRUCTURED-DATA 或附加到 MSG
- 从 APP-NAME 和 PROCID 重建 TAG
从 RFC 3164 转换到本规范:
- 将 VERSION 设置为 1
- 向时间戳添加当前年份
- 使用中继的时区或 UTC
- 将 TAG 解析为 APP-NAME 和 PROCID (尽力而为)
- 如果无法确定,则将 MSGID 设置为 NILVALUE

A.2. 消息长度 (Message Length)

接收方所需的最小容量 480 字节具有实际意义:

为什么是 480 字节?

在许多网络上不分片的单个 UDP 数据包
在降级网络中更高的传递可能性
与有限实现的兼容性

影响:

关键消息: 安全警报和操作紧急情况应在 480 字节内
故障排除数据: 保持诊断消息紧凑
重要数据优先: 将关键信息放在消息的早期

更大的消息:

许多现代部署支持更大的消息:

TLS 传输通常允许数十或数百千字节
TCP 传输没有实际大小限制
现代实现通常支持 2048、8192 或更大的消息

最佳实践:

根据部署要求配置最大消息大小
对重要元数据使用 STRUCTURED-DATA (计入消息长度)
在您的环境中测试最大消息大小
实现对超大消息的优雅处理 (截断或拒绝)
在收集器监控截断的消息

UTF-8 考虑事项:

消息长度以字节而非字符测量。如果包含非 ASCII 字符,1000 字符的 UTF-8 字符串可能是 3000 字节或更多。实施者在确定消息大小时必须考虑这一点。

A.3. 严重性值 (Severity Values)

正确使用严重性值可以提高消息的实用性。

指南:

Emergency (0): 谨慎用于真正的紧急情况
- 系统完全不可用
- 关键硬件即将故障
- 正在发生数据丢失
Alert (1): 需要立即采取行动
- 服务中断
- 检测到安全漏洞
- 关键资源即将耗尽
Critical (2): 危急情况
- 硬盘故障
- 主网络连接丢失
- 应用程序崩溃
Error (3): 错误情况
- 非关键服务故障
- 可恢复的错误
- 连接超时
Warning (4): 警告情况
- 资源使用接近限制
- 使用了已弃用的功能
- 配置问题
Notice (5): 正常但重要
- 服务启动/停止
- 配置更改
- 安全相关的正常事件
Informational (6): 信息性消息
- 日常操作
- 状态消息
- 连接建立
Debug (7): 调试级消息
- 详细诊断信息
- 面向开发人员的消息
- 应在生产中禁用

配置考虑事项:

允许管理员:

根据部署需求调整严重性分配
按严重性过滤消息
将严重性路由到不同的收集器
覆盖特定消息类型的严重性

避免严重性滥用:

不要将所有消息标记为 Emergency
不要对生产事件使用 Debug 严重性
考虑操作员警报疲劳

A.4. TIME-SECFRAC 精度

TIMESTAMP 字段支持最多 6 位数字 (微秒) 的秒小数部分。

常见错误:

删除前导零:

错误: 2003-10-11T22:13:14.3      (看起来是 300ms)
正确: 2003-10-11T22:13:14.003    (实际上是 3ms)

精度建议:

对大多数应用程序使用毫秒 (3 位数字)
对高精度计时使用微秒 (6 位数字)
如果不需要亚秒精度,则省略秒小数部分
确保时间同步 (NTP) 支持所需的精度

实施注意事项:

并非所有系统都能提供微秒精度。可以接受:

提供少于 6 位数字的精度
四舍五入或截断到可用精度
如果精度不可用,则完全省略 TIME-SECFRAC

A.5. 名称大小写约定 (Case Convention for Names)

本文档对 SD-ID 和 PARAM-NAME 使用"小写驼峰式"。

约定:

首字母小写
后续单词首字母大写
无连字符或下划线

示例:

timeQuality
syncAccuracy
enterpriseId
myCompanyName

优点:

实现之间的一致性
可读性
与各种编程语言的兼容性

建议:

对以下内容使用此约定:

新的 SD-ID
PARAM-NAME
扩展标识符

私有实现可以使用其他约定,但建议保持一致性。

A.6. 不知道时间的 Syslog 应用程序

第 6.2.3 节允许在时间未知时对 TIMESTAMP 使用 NILVALUE。

何时对 TIMESTAMP 使用 NILVALUE:

没有实时时钟的嵌入式系统
时间同步之前的启动时消息
时间检索失败的系统

何时不使用 NILVALUE:

当操作系统提供时间函数时
当懒惰的实现想要避免时间处理时
当时间可用但不方便获取时

最佳实践:

尽可能发出有效的 TIMESTAMP
仅在真正无法获取时间时使用 NILVALUE
考虑时区与精度的权衡
在您的实现中记录时间处理

中继处理:

接收带有 NILVALUE TIMESTAMP 的消息的中继可以:

按原样转发
用中继的当前时间替换
删除消息 (如果策略要求时间戳)

配置应控制此行为。

A.7. 关于 timeQuality SD-ID 的注意事项

timeQuality SD-ID 提供有关时间戳准确性的宝贵元数据。

tzKnown 参数:

默认应为 0 (未知),除非:

管理员明确配置了时区
操作系统提供可靠的时区信息
系统已针对外部源验证了时区

isSynced 参数:

仅在以下情况下设置为 1:

NTP 或其他时间同步处于活动状态
同步已验证成功
时间源受信任

syncAccuracy 参数:

仅在以下情况下提供:

实际精度已知 (来自 NTP 统计信息)
管理员已配置预期精度
测量数据支持声明

不要夸大精度:

虚假精度会损害对日志的信任。最好:

如果不确定,则完全省略 timeQuality
提供保守的精度估计
记录精度声明

A.8. UTF-8 编码和 BOM

BOM (字节顺序标记) 在 MSG 字段中表示 UTF-8 编码。

BOM 详细信息:

字节序列: 0xEF 0xBB 0xBF
出现在 MSG 字段的开头
表示后面是 UTF-8 编码

何时包含 BOM:

当 MSG 包含 UTF-8 编码文本时
当存在 UTF-8 编码的确定性时
为了与组织策略保持一致

何时省略 BOM:

当 MSG 编码未知或不确定时
当 MSG 包含二进制数据时
为了与不处理 BOM 的系统向后兼容

接收方处理:

接收方应:

检测 BOM 是否存在
相应地处理 UTF-8
处理没有 BOM 的消息 (假设编码未知)
不向最终用户显示 BOM

中继处理:

转发消息的中继应:

如果存在则保留 BOM
除非转码为 UTF-8,否则不添加 BOM
除非转码为另一种编码,否则不删除 BOM

A.1. 与 BSD Syslog 的关系​

A.2. 消息长度 (Message Length)​

A.3. 严重性值 (Severity Values)​

A.4. TIME-SECFRAC 精度​

A.5. 名称大小写约定 (Case Convention for Names)​

A.6. 不知道时间的 Syslog 应用程序​

A.7. 关于 timeQuality SD-ID 的注意事项​

A.8. UTF-8 编码和 BOM​