## BitLogger Update Changes version 0.3.0 ### Feature - feat: add `config.mbt` as a minimal JSON-backed logger configuration layer - feat: add `TextFormatterConfig`, `QueueConfig`, and `LoggerConfig` public config types - feat: add `TextFormatterConfig::new(...)`, `QueueConfig::new(...)`, and `LoggerConfig::new(...)` constructors for explicit config assembly - feat: add `SinkKind` and `SinkConfig` for sink-specific configuration - feat: add `TextFormatterConfig::to_formatter()` for bridging parsed config into runtime formatter setup - feat: add `parse_logger_config_text(...)` for JSON config parsing - 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: add `AsyncLoggerBuildConfig`, `parse_async_logger_build_config_text(...)`, and `build_async_logger(...)` for config-driven async logger assembly - feat: add async lifecycle helpers `shutdown()`, `is_closed()`, `is_running()`, `has_failed()`, and `last_error()` for safer worker teardown and observability - feat: add `parse_async_logger_config_text(...)`, `stringify_async_logger_config(...)`, and build-config serialization helpers for async config roundtrip support - feat: add async batching controls `max_batch` and `flush=Never|Batch|Shutdown` for queue draining and flush timing - 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 - feat: add `TextFormatter.template` and `TextFormatterConfig.template` for template-driven text rendering - feat: support formatter tokens `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}` in both runtime and JSON config paths - feat: add `FileRotation`, `file_rotation(...)`, and size-based file rotation with retained backups for `file_sink(...)` - feat: support `sink.rotation.max_bytes` and `sink.rotation.max_backups` in JSON logger config - feat: add `FileSink::reopen()` and basic file sink failure counters via `open_failures()`, `write_failures()`, and `flush_failures()` - feat: forward file sink reopen and failure-counter helpers through `RuntimeSink` and `ConfiguredLogger` - feat: add explicit `file_flush()` and `file_close()` helpers for config-built file sinks, including queued file sink drain-before-close behavior - feat: make file append mode queryable via `append_mode()` / `file_append_mode()` and persist explicit `reopen(append=...)` mode updates for later reopen calls - feat: add `path()` / `auto_flush_enabled()` on `FileSink` and `file_path()` / `file_auto_flush()` on `ConfiguredLogger` for basic file-policy introspection - feat: add `rotation_enabled()` / `rotation_config()` on `FileSink` and `file_rotation_enabled()` / `file_rotation_config()` on `ConfiguredLogger` for rotation-policy introspection - feat: add runtime file-policy mutators `set_auto_flush(...)`, `set_rotation(...)`, `clear_rotation()` and corresponding configured-logger forwarding helpers - feat: add explicit append-policy setter `set_append_mode(...)` / `file_set_append_mode(...)` so append strategy can be updated without piggybacking on `reopen(...)` - feat: add explicit `reopen_with_current_policy()` / `file_reopen_with_current_policy()` helpers so stored append-policy reopen is discoverable instead of implicit - feat: add `reopen_append()` / `reopen_truncate()` and configured-logger forwarding helpers so common append-vs-truncate reopen flows do not need raw `Some(true/false)` calls - feat: add `FileSinkState`, `FileSink::state()`, and `file_state()` helpers so file-sink runtime policy and failure counters can be read as one snapshot - feat: add `RuntimeFileState` and `file_runtime_state()` so config-built queued file sinks can expose outer queue backlog/drop state together with inner file state - feat: add JSON export helpers for `FileSinkState` and `RuntimeFileState` so runtime file snapshots can be dumped directly for diagnostics - feat: add `reset_failure_counters()` / `file_reset_failure_counters()` so file failure counters can be cleared after diagnostics or recovery handling - feat: add `reset_policy()` / `file_reset_policy()` so runtime append, auto-flush, and rotation settings can be restored to their initial defaults - feat: add `SplitSink`, `split_sink(...)`, and `split_by_level(...)` for routing records into different sinks by predicate or level - feat: add `Logger::bind(...)` as an ergonomic context-binding alias and `fields(...)` helper for tuple-based field construction ### Test - test: cover parsing of core logger config fields - test: cover nested formatter and queue config parsing - test: cover config stringify and parse roundtrip behavior - 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 - test: cover template-based formatter rendering and disabled token behavior - test: cover file rotation config parsing, config roundtrip, and native rotation behavior - test: cover file sink reopen behavior and backend-dependent failure counter paths - test: cover config-built file logger reopen and failure-counter helper access - test: cover config-built file logger flush/close helpers and queued-file drain semantics - test: cover append-mode observability and reopen-mode persistence for direct and config-built file sinks - test: cover path and auto-flush introspection for direct and config-built file sinks - test: cover rotation introspection for direct and config-built file sinks with and without configured rotation - test: cover runtime auto-flush and rotation policy mutation for direct and config-built file sinks - test: cover append-policy setter behavior and confirm subsequent reopen calls inherit the updated append mode - test: cover split sink predicate routing and level-based routing behavior - test: cover `bind(...)` context composition and `fields(...)` helper behavior - test: add async logger lifecycle, config roundtrip, and batching/flush policy test seeds - 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 `examples/async_basic` to use unified JSON-driven async logger config - docs: update root README, English README, and Mooncake README with config usage notes - docs: update formatter examples to demonstrate template-based text rendering - docs: update file sink examples to demonstrate rotation and backup retention - docs: document file sink reopen and observability counters in README variants - docs: clarify that config-built file loggers keep file control and observability helpers - docs: document explicit file flush/close helpers for config-built file loggers - docs: clarify append-mode observability and reopen append-policy semantics - docs: document file path and auto-flush introspection helpers - docs: document rotation introspection helpers for direct and config-built file sinks - docs: document runtime file-policy setter helpers for direct and config-built file sinks - docs: clarify explicit append-policy setter semantics for direct and config-built file sinks - docs: add split sink examples for level-based routing - docs: add `bind(...)` examples for reusable context binding - 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 - formatter templates are intentionally limited to simple token replacement and do not yet include conditional blocks or alignment/padding controls - current file rotation scope is intentionally limited to size-based rename retention and does not yet include time rotation or compression - file sink observability is currently counter-based and explicit; it does not yet attempt automatic recovery or background self-healing - queue wrapping remains synchronous drain-based delivery, not async runtime scheduling - async logging remains an isolated adapter layer and currently targets `native/llvm` only