From 571e41e089945d9791e085b1f0d7c802de7c4064 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Fri, 8 May 2026 17:29:06 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20async=20logger=20adap?= =?UTF-8?q?ter=20package?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 ++++++++ docs/README-en.md | 8 ++++++++ docs/changes/0.3.0.md | 9 +++++++++ 3 files changed, 25 insertions(+) diff --git a/README.md b/README.md index c3e6bc3..32bea3a 100644 --- a/README.md +++ b/README.md @@ -181,3 +181,11 @@ if native_files_supported() { - 已支持字段：`min_level`、`target`、`timestamp`、`sink.kind`、`sink.path`、`sink.append`、`sink.auto_flush`、`sink.text_formatter`、`queue` - 当前可由配置直接组装的 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(...)` +- 推荐启动方式见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1) +- 这层目前仅面向 `native/llvm` backend；它是独立 adapter，不会污染现有同步 core diff --git a/docs/README-en.md b/docs/README-en.md index 4e3864c..79cb1aa 100644 --- a/docs/README-en.md +++ b/docs/README-en.md @@ -170,3 +170,11 @@ if native_files_supported() { - Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`. - Config-driven sink assembly currently supports `console`, `json_console`, `text_console`, and `file`. - `queue` remains a synchronous bounded wrapper around the final sink, not an async runtime. + +## Async Layer + +- A separate `bitlogger_async/` package is now included. +- It uses `moonbitlang/async` and provides `AsyncLogger`, `async_logger(...)`, a background `run()` worker, and bounded async queue delivery. +- The current async API already supports `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, and `child(...)`. +- The recommended startup pattern is shown in [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1). +- This layer currently targets `native/llvm` only and remains isolated from the synchronous logger core. diff --git a/docs/changes/0.3.0.md b/docs/changes/0.3.0.md index fb96987..d3ff573 100644 --- a/docs/changes/0.3.0.md +++ b/docs/changes/0.3.0.md @@ -13,6 +13,11 @@ version 0.3.0 - feat: add `logger_config_to_json(...)` and `stringify_logger_config(...)` for config serialization - feat: add `RuntimeSink`, `ConfiguredLogger`, `build_logger(...)`, and `parse_and_build_logger(...)` for config-driven logger assembly - feat: add `ConfiguredLogger::drain(...)`, `ConfiguredLogger::pending_count()`, and `ConfiguredLogger::dropped_count()` queue observability helpers +- feat: add `bitlogger_async/` as a separate native-target async adapter package +- feat: add `AsyncLogger`, `async_logger(...)`, `run()`, `wait_idle()`, `close()`, `pending_count()`, and `dropped_count()` on top of `moonbitlang/async` +- feat: add async logger composition helpers `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, `child(...)`, and `with_timestamp(...)` +- feat: expose `Record::new(...)` for adapter and integration layers +- fix: repair native file backend FFI declarations so native target checks succeed again - feat: support config keys `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue` - feat: support config-driven sink assembly for `console`, `json_console`, `text_console`, and `file` - feat: use `maria/json_parser` as the first external dependency for practical config loading @@ -25,15 +30,19 @@ version 0.3.0 - test: cover config-built queued text logger flushing and pending count behavior - test: cover partial drain behavior for config-built queued logger - test: cover dropped-count reporting for bounded config-built queue +- build: verify `bitlogger_async --target native` and `examples/async_basic --target native` compile successfully ### Example - docs: update `examples/basic` with JSON config loading example - docs: update `examples/basic` to use `parse_and_build_logger(...)` with explicit error handling in `main` +- docs: add `examples/async_basic` to show async worker startup and queue-backed logging flow - docs: update root README, English README, and Mooncake README with config usage notes +- docs: update root README and English README with async adapter notes and current scope - chore: ignore local `.mooncakes/` cache directory in git ### Notes - current config scope is still intentionally constrained to stable built-in sink shapes - queue wrapping remains synchronous drain-based delivery, not async runtime scheduling +- async logging remains an isolated adapter layer and currently targets `native/llvm` only