MoonLogTrace

MoonLogTrace 是一个纯 MoonBit 的结构化日志与轻量追踪库，面向需要可测试、可回放内存日志的 MoonBit 应用。项目采用不可变值风格，提供日志级别过滤、结构化字段、安全序列化、滚动窗口、查询、保留策略、Span、上下文和统计辅助工具。

安装

moon add CCllff-jpg/MoonLogTrace@0.1.3

模块名以 moon.mod 为准：CCllff-jpg/MoonLogTrace。

快速开始

Logger 是持久化值；每次写日志后应接收返回的新 Logger。

let logger = Logger::new()
  .level(Level::INFO)
  .add_context("service", "billing")
  .build()
let logger = logger.info("server started", [("port", "8080")])
let logger = logger.warn("disk space low", [("free_gb", "2.3")])

let records = logger.records()
let lines = logger.logs()

运行仓库演示：

moon run cmd/main

核心能力

• 5 级日志：TRACE、DEBUG、INFO、WARN、ERROR。
• 结构化记录：消息、级别、字符串字段和逻辑序列时间戳。
• 12 个格式化入口：文本、Plain、JSON、NDJSON、ANSI Color、Compact、CSV、Pattern、logfmt、XML、Syslog 风格和 GELF 风格。
• 内存输出：MemoryAppender 和有界 RollingAppender 均采用防御性复制。
• 真实回放：LogReplay::from_logger 读取 Logger 的结构化记录，replay_into 保留原始字段、级别和时间戳。
• 查询与保留：按级别、消息、字段、时间范围和数量查询；按最低级别、最大年龄和最大条数保留。
• 上下文与追踪：LogContext、CorrelationId、RequestContext、Span。
• 辅助组件：过滤器、Pipeline、批量收集、路由、采样、轮转策略、统计和告警规则。

滚动窗口

let rolling = RollingAppender::new(2)
  .append(LogRecord::new(Level::INFO, "one", [], 1))
  .append(LogRecord::new(Level::WARN, "two", [], 2))
  .append(LogRecord::new(Level::ERROR, "three", [], 3))

assert_eq(rolling.count(), 2)
assert_eq(rolling.dropped(), 1)

容量小于或等于 0 时不会保留记录，但会统计被丢弃数量。

回放、查询与保留

let replay = LogReplay::from_logger(logger)
let (_, replayed) = replay.replay_into(Logger::new().build())

let warnings = logger.query(
  LogQuery::new()
    .min_level(Level::WARN)
    .field_exists("service")
    .limit(100),
)

let retention = logger.apply_retention(
  RetentionPolicy::new()
    .min_level(Level::INFO)
    .max_age(1000)
    .max_count(500),
  2000,
)
let kept = retention.get_records()

查询的 since / until 边界为闭区间。保留策略先按级别和年龄过滤，再在结果超过容量时保留最新记录，并分别报告三类丢弃数量。

输出安全

• JSON、NDJSON 和 GELF 字符串使用 MoonBit 核心 JSON 编码生成完整转义。
• XML 会转义实体并替换 XML 1.0 不允许的控制字符。
• logfmt 会处理空值、空白、引号、反斜杠和控制字符，并规范化字段键。
• CSV 使用双引号重复规则处理逗号、引号和换行。
• Syslog 风格输出会清理 header token，并转义结构化数据和消息中的敏感字符。

这些函数只负责生成字符串，不负责文件写入、网络传输或协议握手。

工程门禁

当前本地工具链为 moon 0.1.20260713。该版本不接受 moon fmt --deny-warn 和 moon info --deny-warn，因此 CI 先检测参数支持情况，并在不支持时执行严格等价门禁：

moon check --deny-warn --target all
moon fmt --check
moon info
git diff --exit-code -- pkg.generated.mbti cmd/main/pkg.generated.mbti
moon test --deny-warn --target all

GitHub Actions 中仍显式保留赛事要求的四个过程和命令文本：moon check、moon fmt --deny-warn、moon info --deny-warn、moon test。

当前边界

• Logger 和 Appender 为同步、内存实现，没有文件、Socket、HTTP 或异步 sink。
• Logger 的 timestamp 是单调递增逻辑序列，不是系统时间；调用保留策略时由调用者提供当前逻辑时间。
• Syslog/GELF 输出是便于集成的字符串格式化，不声明完整传输协议或标准一致性认证。
• 结构化字段当前是 Array[(String, String)]；复杂嵌套值需由调用者先序列化。
• 不可变 API 需要显式重新绑定返回值。

项目状态

• MoonBit 源码：29 个文件，3,125 行。
• 测试：3 个文件，929 行，97 项测试。
• .mbt 总计：32 个文件，4,054 行。
• 许可证：Apache-2.0。

详细开发记录和验收证据位于 docs/competition。