✨ Add file state JSON export helpers

2026-05-30 15:42:25 +00:00 · 2026-05-10 13:05:06 +08:00
parent 41c9ca3eb8
commit d209b7d618
7 changed files with 220 additions and 23 deletions
@@ -240,6 +240,67 @@ test "configured logger exposes file sink observability helpers" {
  ignore(logger.close())
 }

+test "file state json helpers stringify stable snapshots" {
+  let plain = file_sink_state_to_json(
+    FileSinkState::new(
+      "demo.log",
+      available=true,
+      append=false,
+      auto_flush=true,
+      rotation=Some(file_rotation(64, max_backups=2)),
+      open_failures=1,
+      write_failures=2,
+      flush_failures=3,
+      rotation_failures=4,
+    ),
+  )
+  inspect(
+    @json_parser.stringify(plain),
+    content="{\"append\":false,\"auto_flush\":true,\"available\":true,\"flush_failures\":3,\"open_failures\":1,\"path\":\"demo.log\",\"rotation\":{\"max_backups\":2,\"max_bytes\":64},\"rotation_failures\":4,\"write_failures\":2}",
+  )
+  inspect(
+    stringify_file_sink_state(
+      FileSinkState::new(
+        "plain.log",
+        available=false,
+        append=true,
+        auto_flush=false,
+        rotation=None,
+        open_failures=0,
+        write_failures=0,
+        flush_failures=0,
+        rotation_failures=0,
+      ),
+    ),
+    content="{\"append\":true,\"auto_flush\":false,\"available\":false,\"flush_failures\":0,\"open_failures\":0,\"path\":\"plain.log\",\"rotation\":null,\"rotation_failures\":0,\"write_failures\":0}",
+  )
+}
+
+test "runtime file state json helpers stringify queue snapshots" {
+  let json = stringify_runtime_file_state(
+    RuntimeFileState::new(
+      FileSinkState::new(
+        "queue.log",
+        available=true,
+        append=true,
+        auto_flush=false,
+        rotation=None,
+        open_failures=0,
+        write_failures=1,
+        flush_failures=2,
+        rotation_failures=3,
+      ),
+      queued=true,
+      pending_count=7,
+      dropped_count=5,
+    ),
+  )
+  inspect(
+    json,
+    content="{\"dropped_count\":5,\"file\":{\"append\":true,\"auto_flush\":false,\"available\":true,\"flush_failures\":2,\"open_failures\":0,\"path\":\"queue.log\",\"rotation\":null,\"rotation_failures\":3,\"write_failures\":1},\"pending_count\":7,\"queued\":true}",
+  )
+}
+
 test "configured logger reports disabled rotation when file sink has none" {
  let logger = build_logger(
    LoggerConfig::new(
@@ -215,6 +215,22 @@ test {
 }
 ```

+```mbt check
+test {
+  let logger = build_logger(
+    LoggerConfig::new(
+      sink=SinkConfig::new(kind=SinkKind::File, path="bitlogger-runtime.log"),
+      queue=Some(QueueConfig::new(16)),
+    ),
+  )
+  logger.info("queued hello")
+  match logger.file_runtime_state() {
+    Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
+    None => ()
+  }
+}
+```
+
 ## File Rotation / 文件轮转

 - basic rotation is size-based / 当前基础轮转为按文件大小触发
@@ -226,6 +242,7 @@ test {
 - `path()` and `auto_flush_enabled()` expose core file sink policy state / `path()` 与 `auto_flush_enabled()` 可读取 file sink 的基础策略状态
 - `rotation_enabled()` and `rotation_config()` expose whether rotation is active and which settings are currently applied / `rotation_enabled()` 与 `rotation_config()` 可读取 rotation 是否启用及当前配置参数
 - `state()` exposes a single file-sink snapshot including path, availability, append policy, auto-flush, rotation config, and failure counters / `state()` 可一次性读取包含 path、availability、append、auto-flush、rotation 配置与失败计数的 file sink 快照
+- `file_sink_state_to_json(...)` / `stringify_file_sink_state(...)` and `runtime_file_state_to_json(...)` / `stringify_runtime_file_state(...)` export snapshots as JSON / `file_sink_state_to_json(...)` / `stringify_file_sink_state(...)` 与 `runtime_file_state_to_json(...)` / `stringify_runtime_file_state(...)` 可将快照直接导出为 JSON
 - `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 与失败计数访问器
@@ -144,6 +144,64 @@ pub struct RuntimeFileState {
  dropped_count : Int
 }

+pub fn RuntimeFileState::new(
+  file : FileSinkState,
+  queued~ : Bool = false,
+  pending_count~ : Int = 0,
+  dropped_count~ : Int = 0,
+) -> RuntimeFileState {
+  { file, queued, pending_count, dropped_count }
+}
+
+fn file_sink_state_to_json_value(state : FileSinkState) -> @json_parser.JsonValue {
+  let obj : Map[String, @json_parser.JsonValue] = {
+    "path": @json_parser.JsonValue::String(state.path),
+    "available": @json_parser.JsonValue::Bool(state.available),
+    "append": @json_parser.JsonValue::Bool(state.append),
+    "auto_flush": @json_parser.JsonValue::Bool(state.auto_flush),
+    "open_failures": @json_parser.JsonValue::Number(state.open_failures.to_double()),
+    "write_failures": @json_parser.JsonValue::Number(state.write_failures.to_double()),
+    "flush_failures": @json_parser.JsonValue::Number(state.flush_failures.to_double()),
+    "rotation_failures": @json_parser.JsonValue::Number(state.rotation_failures.to_double()),
+  }
+  match state.rotation {
+    None => obj["rotation"] = @json_parser.JsonValue::Null
+    Some(rotation) => obj["rotation"] = file_rotation_config_to_json(rotation)
+  }
+  @json_parser.JsonValue::Object(obj)
+}
+
+pub fn file_sink_state_to_json(state : FileSinkState) -> @json_parser.JsonValue {
+  file_sink_state_to_json_value(state)
+}
+
+pub fn stringify_file_sink_state(state : FileSinkState, pretty~ : Bool = false) -> String {
+  let value = file_sink_state_to_json_value(state)
+  if pretty {
+    @json_parser.stringify_pretty(value, 2)
+  } else {
+    @json_parser.stringify(value)
+  }
+}
+
+pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.JsonValue {
+  @json_parser.JsonValue::Object({
+    "file": file_sink_state_to_json_value(state.file),
+    "queued": @json_parser.JsonValue::Bool(state.queued),
+    "pending_count": @json_parser.JsonValue::Number(state.pending_count.to_double()),
+    "dropped_count": @json_parser.JsonValue::Number(state.dropped_count.to_double()),
+  })
+}
+
+pub fn stringify_runtime_file_state(state : RuntimeFileState, pretty~ : Bool = false) -> String {
+  let value = runtime_file_state_to_json(state)
+  if pretty {
+    @json_parser.stringify_pretty(value, 2)
+  } else {
+    @json_parser.stringify(value)
+  }
+}
+
 pub impl Sink for RuntimeSink with write(self, rec) {
  match self {
    Console(sink) => sink.write(rec)
@@ -416,34 +474,31 @@ pub fn RuntimeSink::file_state(self : RuntimeSink) -> FileSinkState {
  match self {
    File(sink) => sink.state()
    QueuedFile(sink) => sink.sink.state()
-    _ => {
-      path: "",
-      available: false,
-      append: false,
-      auto_flush: false,
-      rotation: None,
-      open_failures: 0,
-      write_failures: 0,
-      flush_failures: 0,
-      rotation_failures: 0,
-    }
+    _ => FileSinkState::new(
+      "",
+      available=false,
+      append=false,
+      auto_flush=false,
+      rotation=None,
+      open_failures=0,
+      write_failures=0,
+      flush_failures=0,
+      rotation_failures=0,
+    )
  }
 }

 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(),
-    })
+    File(sink) => Some(RuntimeFileState::new(sink.state()))
+    QueuedFile(sink) => Some(
+      RuntimeFileState::new(
+        sink.sink.state(),
+        queued=true,
+        pending_count=sink.pending_count(),
+        dropped_count=sink.dropped_count(),
+      ),
+    )
    _ => None
  }
 }
@@ -74,6 +74,30 @@ pub struct FileSinkState {
  rotation_failures : Int
 }

+pub fn FileSinkState::new(
+  path : String,
+  available~ : Bool = false,
+  append~ : Bool = true,
+  auto_flush~ : Bool = true,
+  rotation~ : FileRotation? = None,
+  open_failures~ : Int = 0,
+  write_failures~ : Int = 0,
+  flush_failures~ : Int = 0,
+  rotation_failures~ : Int = 0,
+) -> FileSinkState {
+  {
+    path,
+    available,
+    append,
+    auto_flush,
+    rotation,
+    open_failures,
+    write_failures,
+    flush_failures,
+    rotation_failures,
+  }
+}
+
 pub fn file_rotation(max_bytes : Int, max_backups~ : Int = 1) -> FileRotation {
  {
    max_bytes: if max_bytes <= 0 { 1 } else { max_bytes },