feat(syslog): 增加积压采样免采样窗口

- 新增 start-lag-ms 配置，默认15分钟内全量保留 - 在15分钟至1小时之间按10级逐步降低保留率 - 延迟达到1小时后使用普通10%、非标20%的最低保留率 - 校验起始延迟必须小于最低保留率阈值 - 状态接口新增 start_lag_ms 配置展示 - 将采样策略版本升级为 v2 - 更新 Docker Compose 和 v4 升级配置说明 - 补充采样时间边界及非法配置单元测试
2026-09-12 23:43:56 +08:00
parent c868e3befd
commit 87fee6fe69
27 changed files with 1777 additions and 94 deletions
@@ -0,0 +1,124 @@
+# v4 积压分级采样与告警优先升级说明
+
+## 升级范围
+
+v4 只升级 `syslog-consumer-rule` 和达梦数据库，不修改 `syslog-serve`，也不新增 Kafka Topic。
+
+本次升级包含：
+
+- 根据消息 `receive_time` 与当前时间的差值，对积压消息分级采样；
+- `syslog_normal_alarm` 始终全量保留，并在 InfluxDB 原文、普通表和非标表之前单独提交；
+- 未被保留的 `syslog_normal_data`、`syslog_non_normal_message` 及对应原文不写入存储；
+- 按消息来源小时、Topic、Partition、策略版本和实际保留率记录采样审计；
+- 审计表不可用时自动回退为全量保留，不执行有损采样；
+- InfluxDB 原文写入变为非关键旁路，启动检查或运行时写入失败只记录并继续主消费。
+
+## 文件与执行顺序
+
+| 顺序 | 文件 | 作用 |
+| --- | --- | --- |
+| 1 | `database/01-backlog-sampling-precheck.sql` | 只读检查目标表、约束和索引是否已经存在 |
+| 2 | `database/02-backlog-sampling-upgrade.sql` | 创建积压采样小时审计表，仅执行一次 |
+| 3 | `database/03-backlog-sampling-verify.sql` | 只读验证表结构，并查看实际保留情况 |
+| 4 | `config/01-new-environment-variables.md` | 核对新增配置，再替换 `syslog-consumer-rule` JAR |
+
+数据库脚本必须使用 `syslog-consumer-rule` 实际连接的达梦用户执行。
+
+## 第一步：升级达梦
+
+先执行：
+
+```text
+database/01-backlog-sampling-precheck.sql
+```
+
+- 如果目标表、约束和索引都不存在，执行 `02-backlog-sampling-upgrade.sql`，再执行
+  `03-backlog-sampling-verify.sql`；
+- 如果目标表已经存在，不要重复执行 `02`，直接执行 `03` 核对结构；
+- 如果只存在部分对象，先停止升级并确认此前执行到哪一步，不要盲目重跑建表脚本。
+
+`03` 验证应满足：
+
+- 返回 `SYSLOG_BACKLOG_RETENTION_HOURLY` 一张表；
+- 表包含 22 个字段；
+- 主键和保留率检查约束状态为 `ENABLED`；
+- 更新时间索引状态为 `VALID`。
+
+## 第二步：配置并升级应用
+
+按 [新增变量配置清单](./config/01-new-environment-variables.md) 核对配置，然后替换并重启
+`syslog-consumer-rule`。只替换 JAR、不增加环境变量时，积压采样也会按 JAR 内置默认值开启，因此必须先
+完成数据库升级。
+
+默认策略如下：
+
+| 消息延迟 | 普通记录保留率 | 非标记录保留率 |
+| --- | ---: | ---: |
+| 不大于 15 分钟 | 100% | 100% |
+| 大于 15、且小于 19.5 分钟 | 100% | 100% |
+| 19.5～小于 24 分钟 | 91% | 92% |
+| 24～小于 28.5 分钟 | 82% | 84% |
+| 28.5～小于 33 分钟 | 73% | 76% |
+| 33～小于 37.5 分钟 | 64% | 68% |
+| 37.5～小于 42 分钟 | 55% | 60% |
+| 42～小于 46.5 分钟 | 46% | 52% |
+| 46.5～小于 51 分钟 | 37% | 44% |
+| 51～小于 55.5 分钟 | 28% | 36% |
+| 55.5～小于 60 分钟 | 19% | 28% |
+| 不小于 60 分钟 | 10% | 20% |
+
+默认前 15 分钟为免采样窗口。之后使用 `（60 分钟 - 15 分钟）÷ 10 = 4.5 分钟` 的阶梯宽度；
+达到 1 小时才使用最低保留率。
+
+采样采用 `event_id` 的确定性哈希：同一策略版本下，同一消息重复处理时选择结果一致。规则计算始终执行，
+只有完成规则计算、确认是否产生告警并成功写入小时审计后，才执行丢弃。
+
+## 写入顺序与故障行为
+
+每个批次按以下顺序处理：
+
+1. 完整规则计算并提交采样审计；
+2. 单独提交全部 `syslog_normal_alarm`；
+3. 写入被保留消息的 InfluxDB 原文；
+4. 写入被保留的 `syslog_normal_data` 和 `syslog_non_normal_message`。
+
+InfluxDB 原文写入默认单次网络阶段最多等待 5 秒；发生依赖故障后，30 秒内快速跳过后续原文请求。启动
+健康检查失败、写入失败以及特殊 DLT 写入失败都只记录日志，不阻塞 Kafka 主消费进度。
+
+## 升级后验证
+
+查看消费和异常日志：
+
+```bash
+docker logs --since 10m syslog-consumer-rule-dm 2>&1 \
+| grep -E 'Syslog批次完成|BACKLOG_SAMPLING|INFLUX_RAW_BYPASS|SYSLOG_CONTINUITY_LOSS' \
+| tail -100
+```
+
+查看运行状态：
+
+```text
+GET /xdrrule/api/syslog/backlog-sampling/status
+GET /xdrrule/api/syslog/raw-storage/metrics
+```
+
+然后执行 `database/03-backlog-sampling-verify.sql` 的最后一段查询。没有延迟消息时，审计查询为空属于正常；
+发生积压后，应能按来源小时看到告警保存数、普通/非标实际保留率和原文丢弃数。
+
+重点确认：
+
+- `alarm_rows_saved` 始终等于 `alarm_rows_total`；
+- `audit_write_failures_total` 和 `audit_fallback_messages_total` 不持续增加；
+- InfluxDB 故障时 Kafka offset 仍继续推进，告警和达梦保留数据仍持续写入；
+- `raw_write_bypassed_messages_total` 增加表示原文旁路失败，不表示主消费停止。
+
+## 回滚
+
+紧急关闭采样可配置：
+
+```yaml
+- SYSLOG_BACKLOG_SAMPLING_ENABLED=false
+```
+
+重建 `syslog-consumer-rule` 容器后，普通、非标及原文恢复全量保留。也可回滚旧 JAR。无论采用哪种方式，
+都保留 `syslog_backlog_retention_hourly` 表，不要删除历史审计数据。