目录

BitLogger

BitLogger 是一个使用 MoonBit 编写的结构化日志库,适合命令行工具、服务和需要统一日志输出的项目。

从第一个日志到扩展能力

BitLogger 的文档按使用路径组织:先完成一个可运行的日志输出,再按需进入文件、配置、异步和组合能力。API 文档保留为精确参考,不需要从 API 文件名开始阅读。

1. 安装

从一个空项目开始:

moon new log-demo
cd log-demo
moon add Nanaloveyuki/BitLogger@0.11.2

2. 写入第一条结构化日志

在应用 package 的 moon.pkg 中导入库:

import {
  "Nanaloveyuki/BitLogger/src" @log,
}

然后在 main.mbt 中创建控制台 logger:

fn main {
  let logger = @log.build_logger(
    @log.console(min_level=@log.Level::Info, target="app"),
  )

  logger.info("server started", fields=[
    @log.field("port", "8080"),
    @log.field("environment", "development"),
  ])
}

运行 moon run 后,记录会携带 level、target、message 和 fields。下一步按实际需求选择:

支持情况

  • BitLogger 当前在 CI 中检查/验证的目标是 native、wasm、js、wasm-gc
  • src-async 及其 utils 只支持 native、wasm、js;wasm-gc 仅提供同步 src 日志。上游 moonbitlang/async@0.22.9 未实现 wasm-gc 运行时。旧 CI 的 wasm-gc 异步测试未实际执行,现已修正支持声明。
  • llvm 目前按实验性目标处理,当前环境未完成验证
  • 文件输出是 native 能力;跨端代码里建议先判断 native_files_supported()
  • src-async 可用,但示例 examples/async_basic 目前仍按 native 入口提供

主要能力

  • 结构化日志:level、target、message、fields
  • 多种输出方式:console、json console、text console、file
  • 可定制文本格式:模板、style tag、颜色控制
  • 配置驱动构建:JSON 与 YAML 都进入 build_logger(...)、build_async_logger(...)
  • 组合能力:queue、filter、patch、fanout、split、callback
  • 异步日志:独立 src-async package
  • 独立异步文件写入使用 src-async.file_sink_async(...) -> AsyncFileSink;配置构建器及 parse/build 变体通过 AsyncRuntimeSink 包装配置生成的同步运行时状态,并在异步文件路径中使用异步文件后端。根 src.file_sink(...) -> FileSink 是同步 API。
  • Trace context:用 OpenTelemetry 标识规范化 trace_id、span_id、trace_flags、trace_state,再绑定为字段

文档

仓库内的 examples/ 目录与 Examples 文档一一对应;文档解释选择、前提、运行命令和后续扩展,源码保持为可执行参考。

开发

本地开发与 CI 由 .moonbit-toolchain 固定工具链归档 0.10.20+65efd5b93,安装对应的编译器、CLI 和 core:moonc v0.10.20+65efd5b93 (2026-11-05)、moon 0.1.20261104。CLI 与编译器版本号不同;归档不可用时安装失败,不回退到 latest。

在仓库根目录安装:

set -eo pipefail
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s -- "$(cat .moonbit-toolchain)"
export PATH="${MOON_HOME:-$HOME/.moon}/bin:$PATH"
moon version --all
moonc -v
moon update

Windows 的 PowerShell 安装使用同一归档:

$env:MOONBIT_INSTALL_VERSION = (Get-Content .moonbit-toolchain -Raw).Trim()
irm https://cli.moonbitlang.com/install/powershell.ps1 | iex

native 构建需要 C 工具链;Windows CI 使用 MSYS2 UCRT64 GCC 和 OpenSSL。依赖使用 moonbitlang/async@0.22.9、moonbit-community/opentelemetry@0.1.8、moonbitstack/moonyaml@0.1.7 与 sujy123456/lunasieve@0.1.0;显式约束 moonbitlang/protobuf@0.2.0,使 OpenTelemetry 的传递依赖也使用最新发布版本。异步 native 测试和示例按现有 CI 在 Linux/macOS 运行。

在安装完成的 Bash 环境中执行主要验证;js 测试需要 Node.js,wasm/wasm-gc 测试使用随工具链安装的 moonrun:

moon fmt --check
moon info
for target in native wasm wasm-gc js; do
  moon check --target "$target" --deny-warn
  moon test --target "$target" --deny-warn
done
for target in native wasm js; do
  moon check src-async --target "$target" --deny-warn
  moon test src-async --target "$target" --deny-warn
done
for example in basic console_basic config_build presets text_formatter style_tags file_rotation async_basic; do
  moon run "examples/$example" --target native
done

native 集成测试会写入仓库内的 logs/;文件轮转示例会在工作目录生成 bitlogger-example.log 及轮转备份,因此这两个目录需要可写。完整 CI 流程见 ci.yml。0.11.2 已在 Linux x86_64 上用固定工具链执行上述检查;native/js/wasm 完整测试为 320/312/312,异步包为 115/108/108,wasm-gc 的同步测试为 204。wasm-gc 不执行异步包测试;macOS/Windows 验证由 CI 提供。

0.9.2 - 2026-11-03

  • 开发和 MoonBit CI 工具链更新到编译器 0.10.19+97801ee1b、CLI 0.1.20261029。
  • 第三方依赖保持不变,包括 moonbitlang/async@0.22.4;公开 API、日志行为和目标支持范围不变。

0.9.1 - 2026-10-27

  • 开发和所有 MoonBit CI 安装(包括 Windows)固定到编译器 0.10.17+d971670cd,对应 CLI 0.1.20261023;第三方依赖版本不变。
  • JSON 时间戳转换改用 Json(value),兼容新工具链且保持 UInt64 的字符串表示不变。
关于

A Simple Logger base on MoonBit.

3.2 MB
邀请码
    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号