BitLogger/README.md at 2e008b649c5e4cee5473a50fbf438018418a29f6

naloveyuki/BitLogger

Fork 0

mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-05-30 15:42:25 +00:00

Files

T

Nanaloveyuki 2e008b649c ✨ Add split sink routing helpers

2026-05-09 22:00:02 +08:00

8.4 KiB

Raw Blame History

<html>

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

Mooncake@Nanaloveyuki/BitLogger

中文 | English

</html>

📖 介绍

BitLogger 是一个基于 MoonBit 编写的结构化日志库。

❇️ 特点

🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 rotation/async 等能力。
🏗️ 结构明确：按 level / record / formatter / sinks / logger / global 拆文件，便于继续维护。
🔌 可扩展：支持 fanout_sink(...) 和 callback_sink(...)，方便后续桥接文件、指标或外部系统。
🔀 可分流：支持 split_sink(...) / split_by_level(...)，可按谓词或 level 将日志路由到不同 sink。
🧱 可组合：支持 buffered_sink(...) 和 filter_sink(...)，可以在不引入复杂 runtime 的前提下组合输出策略。
🔎 可复用过滤：提供 target_has_prefix(...)、message_contains(...)、level_at_least(...)、field_equals(...) 等过滤辅助函数。
🩹 可变换 Record：支持 with_patch(...)、patch_sink(...) 与脱敏/补字段/message 变换 helper。
📮 显式队列：支持 queued_sink(...) / with_queue(...)、有界积压与溢出策略，作为后续 async sink 的 runtime-safe 基础。
🧾 可配置文本格式：支持 text_formatter(...)、format_text(...)、text_console_sink(...)、formatted_callback_sink(...) 与模板化 template 输出。
💾 Native 文件输出：支持 file_sink(...)，并已提供基础 size rotation / backup retention；当前仅保证 native/llvm backend 可用。
📦 面向 MoonBit：API 和工程结构围绕 MoonBit 的 package / visibility / toolchain 现实约束设计。

🚀 快速开始

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 示例

let worker = Logger::new(console_sink(), target="app").child("worker")
worker.info("job ready")

自定义 callback sink 示例

let hook = Logger::new(
  callback_sink(fn(rec) {
    println("callback saw [\{rec.target}] \{rec.message}")
  }),
  target="hook",
)

hook.info("hello")

基础 buffered sink 示例

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 示例

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 示例

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 示例

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")])

显式 queue sink 示例

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 示例

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 示例

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 配置加载示例

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 示例

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())
}

📂 仓库结构

bitlogger/：MoonBit 库 package，本体实现、测试与 Mooncake README
examples/basic/：最小可运行示例

🔗 相关文档

📝 配置说明

当前提供 JSON 配置层：parse_logger_config_text(...)、stringify_logger_config(...)、build_logger(...)
已支持字段：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
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
这层目前仅面向 native/llvm backend；它是独立 adapter，不会污染现有同步 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

8.4 KiB Raw Blame History Unescape Escape