2026 MoonBit 国产基础软件生态开源大赛参赛作品

Mooncake@Nanaloveyuki/BitLogger
中文 | English
## 📖 介绍 BitLogger 是一个使用 MoonBit 编写的结构化日志库 ## ❇️ 特点 - 🧩 基础能力: 支持 level, formatter, sink, context field 和全局 logger. - 🏗️ 结构清晰: 按 `level / record / formatter / sinks / logger / global` 拆分文件, 便于维护. - 🔌 可扩展: 支持 `fanout_sink(...)` 和 `callback_sink(...)`, 方便接入文件, 指标或外部系统. - 🔀 可分流: 支持 `split_sink(...)` / `split_by_level(...)`, 可按谓词或 level 将日志路由到不同 sink. - 🧱 可组合: 支持 `buffered_sink(...)` 和 `filter_sink(...)`, 可以组合不同输出策略. - 🔎 可复用过滤: 提供 `target_has_prefix(...)`, `message_contains(...)`, `level_at_least(...)`, `field_equals(...)` 等过滤辅助函数. - 🩹 可变换 Record: 支持 `with_patch(...)`, `patch_sink(...)` 以及脱敏, 补字段, message 变换 helper. - 🧷 可绑定上下文: 支持 `bind(...)` 与 `fields(...)`, 便于复用上下文字段. - 📮 显式队列: 支持 `queued_sink(...)` / `with_queue(...)`, 支持有界积压和溢出策略. - 🧾 可配置文本格式: 支持 `text_formatter(...)`, `format_text(...)`, `text_console_sink(...)`, `formatted_callback_sink(...)` 和模板化 `template` 输出. - 💾 Native 文件输出: 支持 `file_sink(...)`, 基础 size rotation / backup retention, 显式 `reopen()` / `reopen_with_current_policy()` / `reopen_append()` / `reopen_truncate()` 与失败计数, 仅在 `native/llvm` backend 可用. - 📦 MoonBit 适配: API 和工程结构与 MoonBit 的 package / visibility / toolchain 模型保持一致. ## 🚀 快速开始 ```moonbit let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo") .with_timestamp() .with_context_fields([field("service", "bitlogger")]) logger.info("starting", fields=[field("port", "8080")]) ```
层级 target 示例 ```moonbit let worker = Logger::new(console_sink(), target="app").child("worker") worker.info("job ready") ```
自定义 callback sink 示例 ```moonbit let hook = Logger::new( callback_sink(fn(rec) { println("callback saw [\{rec.target}] \{rec.message}") }), target="hook", ) hook.info("hello") ```
基础 buffered sink 示例 ```moonbit let sink = buffered_sink(console_sink(), flush_limit=2) let logger = Logger::new(sink, target="buffered") logger.info("one") logger.info("two") sink.flush() ```
基础 filter sink 示例 ```moonbit let sink = filter_sink(console_sink(), fn(rec) { rec.target == "kept" }) let kept = Logger::new(sink, target="kept") let dropped = Logger::new(sink, target="dropped") kept.info("visible") dropped.info("hidden") ```
Logger 链式 filter 示例 ```moonbit let logger = Logger::new(console_sink(), target="service") .with_filter(all_of([ target_has_prefix("service"), message_contains("visible"), ])) logger.info("hidden") logger.child("api").info("visible") ```
Record patch 示例 ```moonbit let logger = Logger::new(console_sink(), target="auth") .with_patch(compose_patches([ prefix_message("[safe] "), redact_fields(["token"]), append_fields([field("service", "bitlogger")]), ])) logger.info("login", fields=[field("user", "alice"), field("token", "secret")]) ```
bind 上下文示例 ```moonbit let logger = Logger::new(console_sink(), target="audit") .bind(fields([("service", "bitlogger"), ("scope", "login")])) logger.info("accepted", fields=[field("user", "alice")]) ```
显式 queue sink 示例 ```moonbit let logger = Logger::new(console_sink(), target="queue") .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest) logger.info("one") logger.info("two") logger.info("three") ignore(logger.sink.flush()) ```
按 level 分流 sink 示例 ```moonbit let logger = Logger::new( split_by_level( callback_sink(fn(rec) { println("high priority: \{rec.level.label()} \{rec.message}") }), console_sink(), min_level=Level::Warn, ), min_level=Level::Trace, target="split", ) logger.info("normal output") logger.warn("warning output") ```
自定义文本 formatter 示例 ```moonbit let formatter = text_formatter( show_timestamp=false, field_separator=",", template="[{level}] {target} {message} :: {fields}", ) let logger = Logger::new(text_console_sink(formatter), target="pretty") logger.info("hello", fields=[field("mode", "pretty")]) ```
JSON 配置加载示例 ```moonbit let config = parse_logger_config_text( "{\"min_level\":\"debug\",\"target\":\"config.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"show_timestamp\":false,\"field_separator\":\",\",\"template\":\"[{level}] {target} {message} :: {fields}\"}},\"queue\":{\"max_pending\":2,\"overflow\":\"DropOldest\"}}", ) let logger = build_logger(config) logger.info("configured from json") ignore(logger.flush()) ```
native 文件 sink 示例 ```moonbit if native_files_supported() { let logger = Logger::new( file_sink("bitlogger.log", rotation=Some(file_rotation(128, max_backups=2))), target="file", ) logger.info("hello", fields=[field("kind", "file")]) ignore(logger.sink.flush()) ignore(logger.sink.close()) } ```
file runtime state dump 示例 ```moonbit let logger = build_logger( LoggerConfig::new( sink=SinkConfig::new(kind=SinkKind::File, path="bitlogger-runtime.log"), queue=Some(QueueConfig::new(16)), ), ) logger.info("queued hello") match logger.file_runtime_state() { Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true)) None => () } ```
## 📂 仓库结构 - `bitlogger/`: MoonBit 库 package, 包含本体实现, 测试与 Mooncake README - `examples/basic/`: 最小可运行示例 - `examples/async_basic/`: 基于 `moonbitlang/async` 的异步 logger 示例 ## 🔗 相关文档 - [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger) - [English README](./docs/README-en.md) ## 📝 配置说明 - 提供 JSON 配置层: `parse_logger_config_text(...)`, `stringify_logger_config(...)`, `build_logger(...)` - `QueueConfig`, `TextFormatterConfig`, `SinkConfig` 可分别通过 `queue_config_to_json(...)` / `stringify_queue_config(...)`, `text_formatter_config_to_json(...)` / `stringify_text_formatter_config(...)`, `sink_config_to_json(...)` / `stringify_sink_config(...)` 单独导出 JSON - 支持字段: `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.rotation`, `sink.text_formatter`, `queue` - `sink.rotation` 支持 `max_bytes` 与 `max_backups`, 用于基础 size-based rotation 和 backup retention - `file_sink(...)` 提供 `reopen()`, `reopen_with_current_policy()`, `reopen_append()`, `reopen_truncate()`, `open_failures()`, `write_failures()`, `flush_failures()`, `rotation_failures()`, 用于基础可观测性 - `file_sink(...)` 提供 `append_mode()`. 显式传入 `reopen(append=...)` 时, 会更新后续 reopen 使用的 append 策略. `reopen_with_current_policy()` 使用当前保存的策略重开文件, `reopen_append()` / `reopen_truncate()` 提供常见的 append 和 truncate 模式 - `file_sink(...)` 支持 `set_append_mode(...)`, 用于修改后续 reopen 使用的 append 策略 - `file_sink(...)` 可读取 `path()` 与 `auto_flush_enabled()` 等基础 file 策略状态 - `file_sink(...)` 提供 `rotation_enabled()` 与 `rotation_config()`, 可查询 rotation 是否启用及其参数 - `file_sink(...)` 提供 `state()`, 可一次性读取 path, available, append, auto_flush, rotation 与各类 failure counter 快照 - `file_sink(...)` 提供 `policy()` 与 `default_policy()`, 可分别读取当前策略与创建时默认策略 - `file_sink(...)` 提供 `policy_matches_default()`, 可判断当前运行期策略是否偏离默认策略 - `file_sink(...)` 支持 `set_policy(...)`, 可一次性写回 append / auto_flush / rotation 三项策略 - `file_sink(...)` 提供 `reset_failure_counters()`, 可清空 open / write / flush / rotation 失败计数 - `file_sink(...)` 提供 `reset_policy()`, 可将 append / auto_flush / rotation 恢复到创建 sink 时的默认策略 - `file_sink(...)` 支持 `set_auto_flush(...)`, `set_rotation(...)`, `clear_rotation()`, 可在运行期调整写出策略 - `build_logger(...)` 产出的 `ConfiguredLogger` 也提供 `file_reopen()`, `file_reopen_with_current_policy()`, `file_reopen_append()`, `file_reopen_truncate()`, `file_flush()`, `file_close()`, `file_append_mode()`, `file_path()`, `file_auto_flush()`, `file_rotation_enabled()`, `file_rotation_config()`, `file_state()`, 以及 `file_set_append_mode(...)`, `file_set_auto_flush(...)`, `file_set_rotation(...)`, `file_clear_rotation()` 和对应的 file failure 计数访问器 - `ConfiguredLogger` 提供 `file_runtime_state()`, 可在 file sink 被 queue 包装时同时读取底层 file 快照, queue 状态, pending 计数与 dropped 计数 - `ConfiguredLogger` 提供 `file_policy()` 与 `file_default_policy()`, 可分别读取当前 file 策略与初始配置策略 - `ConfiguredLogger` 提供 `file_policy_matches_default()`, 可判断当前配置式 file 策略是否偏离默认值 - `ConfiguredLogger` 支持 `file_set_policy(...)`, 可一次性改写配置式 file sink 的当前运行期策略 - `ConfiguredLogger` 支持 `file_reset_failure_counters()`, 可在配置式 file sink 上统一清空失败计数 - `ConfiguredLogger` 支持 `file_reset_policy()`, 可将配置式 file sink 的运行期策略恢复到初始配置 - `file_sink_policy_to_json(...)`, `stringify_file_sink_policy(...)` 可将独立 file policy 直接导出为 JSON, 便于策略快照, 配置对比或诊断上报 - `file_sink_state_to_json(...)`, `stringify_file_sink_state(...)`, `runtime_file_state_to_json(...)`, `stringify_runtime_file_state(...)` 可直接把 file / queued-file 快照导出为 JSON, 便于排障或上报 - `sink.text_formatter.template` 支持固定 token: `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, `{fields}` - 可由配置直接组装的 sink 类型: `console`, `json_console`, `text_console`, `file` - `queue` 作为显式包装层附着在最终 sink 外侧. 这仍然是同步 drain 模型, 不是 async runtime ## 🧵 异步层 - 提供独立 package: `bitlogger_async/` - 异步层基于 `moonbitlang/async`, 提供 `AsyncLogger`, `async_logger(...)`, 后台 `run()` worker 与有界 async queue - async API 支持 `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, `child(...)` - 建议使用 `shutdown()` 停止 worker. 默认模式下, 它会先等待队列清空, 再关闭 queue, 最后等待 worker 退出 - 提供基础生命周期观测: `is_closed()`, `is_running()`, `has_failed()`, `last_error()` - async worker 支持 `max_batch` 批量消费, 以及 `flush=Never|Batch|Shutdown` 的基础 flush 策略 - 示例见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1) - 仅支持 `native/llvm` backend, 与同步 core 分开维护 ### Async Config - 提供 `parse_async_logger_config_text(...)`, `stringify_async_logger_config(...)`, `parse_async_logger_build_config_text(...)`, `build_async_logger(...)` - JSON 顶层结构分为两个字段: `logger` 与 `async_config` - `logger` 复用同步 `LoggerConfig` 的 schema, `async_config` 支持 `max_pending`, `overflow`, `max_batch`, `flush` - 用法可参考 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1)