diff --git a/README.md b/README.md index 59b2e8b..b219b37 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,7 @@ if native_files_supported() { - `file_sink(...)` 还提供 `state()`,可一次性读取 path、available、append、auto_flush、rotation 与各类 failure counter 快照 - `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 计数 - `sink.text_formatter.template` 当前支持固定 token:`{timestamp}`、`{timestamp_ms}`、`{level}`、`{target}`、`{message}`、`{fields}` - 当前可由配置直接组装的 sink 类型:`console`、`json_console`、`text_console`、`file` - `queue` 会作为显式包装层附着在最终 sink 外侧;这仍然是同步 drain 模型,不是 async runtime diff --git a/bitlogger/BitLogger_test.mbt b/bitlogger/BitLogger_test.mbt index ef98523..009509f 100644 --- a/bitlogger/BitLogger_test.mbt +++ b/bitlogger/BitLogger_test.mbt @@ -207,6 +207,7 @@ test "configured logger exposes file sink observability helpers" { ), ) let state = logger.file_state() + let runtime_state = logger.file_runtime_state() inspect(logger.file_available() == native_files_supported(), content="true") inspect(logger.file_path(), content="config-file.log") inspect(state.path, content="config-file.log") @@ -215,6 +216,15 @@ test "configured logger exposes file sink observability helpers" { inspect(state.auto_flush == logger.file_auto_flush(), content="true") inspect(logger.file_append_mode(), content="true") inspect(logger.file_auto_flush(), content="false") + match runtime_state { + Some(snapshot) => { + inspect(snapshot.queued, content="false") + inspect(snapshot.pending_count, content="0") + inspect(snapshot.dropped_count, content="0") + inspect(snapshot.file.path, content="config-file.log") + } + None => inspect(false, content="true") + } inspect(logger.file_rotation_enabled(), content="true") match logger.file_rotation_config() { Some(rotation) => { @@ -238,9 +248,20 @@ test "configured logger reports disabled rotation when file sink has none" { ) inspect(logger.file_rotation_enabled(), content="false") inspect(logger.file_rotation_config() is None, content="true") + match logger.file_runtime_state() { + Some(snapshot) => inspect(snapshot.queued, content="false") + None => inspect(false, content="true") + } ignore(logger.close()) } +test "configured non-file logger has no file runtime state" { + let logger = build_logger( + LoggerConfig::new(sink=SinkConfig::new(kind=SinkKind::Console)), + ) + inspect(logger.file_runtime_state() is None, content="true") +} + test "configured logger file setters update file sink policy state" { let logger = build_logger( LoggerConfig::new( @@ -343,15 +364,31 @@ test "configured queued file logger flushes queue through file helper" { ) logger.info("one") logger.info("two") + match logger.file_runtime_state() { + Some(snapshot) => { + inspect(snapshot.queued, content="true") + inspect(snapshot.pending_count, content="2") + inspect(snapshot.dropped_count, content="0") + } + None => inspect(false, content="true") + } if logger.file_available() { inspect(logger.pending_count(), content="2") inspect(logger.file_flush(), content="true") inspect(logger.pending_count(), content="0") + match logger.file_runtime_state() { + Some(snapshot) => inspect(snapshot.pending_count, content="0") + None => inspect(false, content="true") + } inspect(logger.file_close(), content="true") } else { inspect(logger.pending_count(), content="2") inspect(logger.file_flush(), content="false") inspect(logger.pending_count(), content="0") + match logger.file_runtime_state() { + Some(snapshot) => inspect(snapshot.pending_count, content="0") + None => inspect(false, content="true") + } inspect(logger.file_close(), content="false") } } diff --git a/bitlogger/README.mbt.md b/bitlogger/README.mbt.md index 9770613..763c364 100644 --- a/bitlogger/README.mbt.md +++ b/bitlogger/README.mbt.md @@ -229,4 +229,5 @@ test { - `set_auto_flush(...)`, `set_rotation(...)`, and `clear_rotation()` allow runtime tuning of core file sink policies / `set_auto_flush(...)`、`set_rotation(...)`、`clear_rotation()` 可在运行期调整 file sink 的基础策略 - `open_failures()`、`write_failures()`、`flush_failures()`、`rotation_failures()` expose basic sink health counters / `open_failures()`、`write_failures()`、`flush_failures()`、`rotation_failures()` 可用于观察基础 sink 健康状态 - `ConfiguredLogger` also forwards file reopen, flush, close, append-mode, path, auto-flush, rotation-config, state snapshot, append setter, policy setter, and failure-counter helpers for config-built file sinks / `ConfiguredLogger` 也会为配置生成的 file sink 转发 reopen、flush、close、append-mode、path、auto-flush、rotation 配置、state 快照、append setter、策略 setter 与失败计数访问器 +- `ConfiguredLogger::file_runtime_state()` also reports whether a file sink is queue-wrapped and exposes the outer queue pending/drop counters together with the inner file snapshot / `ConfiguredLogger::file_runtime_state()` 还可报告 file sink 是否被 queue 包装,并将外层 queue 的 pending/drop 计数与内层 file 快照一起返回 - current scope is observability-first, not a full self-healing sink runtime / 当前定位仍以可观测性优先,不是完整自愈型 sink runtime diff --git a/bitlogger/config.mbt b/bitlogger/config.mbt index 5050cb6..97fa3fa 100644 --- a/bitlogger/config.mbt +++ b/bitlogger/config.mbt @@ -137,6 +137,13 @@ pub(all) enum RuntimeSink { QueuedFile(QueuedSink[FileSink]) } +pub struct RuntimeFileState { + file : FileSinkState + queued : Bool + pending_count : Int + dropped_count : Int +} + pub impl Sink for RuntimeSink with write(self, rec) { match self { Console(sink) => sink.write(rec) @@ -423,6 +430,24 @@ pub fn RuntimeSink::file_state(self : RuntimeSink) -> FileSinkState { } } +pub fn RuntimeSink::file_runtime_state(self : RuntimeSink) -> RuntimeFileState? { + match self { + File(sink) => Some({ + file: sink.state(), + queued: false, + pending_count: 0, + dropped_count: 0, + }) + QueuedFile(sink) => Some({ + file: sink.sink.state(), + queued: true, + pending_count: sink.pending_count(), + dropped_count: sink.dropped_count(), + }) + _ => None + } +} + pub type ConfiguredLogger = Logger[RuntimeSink] pub fn ConfiguredLogger::flush(self : ConfiguredLogger) -> Int { @@ -532,6 +557,10 @@ pub fn ConfiguredLogger::file_state(self : ConfiguredLogger) -> FileSinkState { self.sink.file_state() } +pub fn ConfiguredLogger::file_runtime_state(self : ConfiguredLogger) -> RuntimeFileState? { + self.sink.file_runtime_state() +} + fn expect_object( value : @json_parser.JsonValue, context : String, diff --git a/docs/README-en.md b/docs/README-en.md index 233674b..586196e 100644 --- a/docs/README-en.md +++ b/docs/README-en.md @@ -214,6 +214,7 @@ if native_files_supported() { - `file_sink(...)` also exposes `state()` for reading a single snapshot that includes path, availability, append policy, auto-flush flag, rotation config, and all current failure counters. - `file_sink(...)` also supports `set_auto_flush(...)`, `set_rotation(...)`, and `clear_rotation()` for runtime policy updates. - `ConfiguredLogger` built through `build_logger(...)` also exposes `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()`, plus `file_set_append_mode(...)`, `file_set_auto_flush(...)`, `file_set_rotation(...)`, `file_clear_rotation()`, and the corresponding file failure counters, so config-driven file logging keeps a usable control surface. +- `ConfiguredLogger` also exposes `file_runtime_state()` so queued file loggers can report both the underlying file snapshot and the outer queue backlog/drop state in one read. - `sink.text_formatter.template` currently supports fixed tokens: `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}`. - 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. diff --git a/docs/changes/0.3.0.md b/docs/changes/0.3.0.md index 4df9981..4ff8030 100644 --- a/docs/changes/0.3.0.md +++ b/docs/changes/0.3.0.md @@ -40,6 +40,7 @@ version 0.3.0 - 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 `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