diff --git a/README.md b/README.md
index b219b37..0fd01c0 100644
--- a/README.md
+++ b/README.md
@@ -206,6 +206,25 @@ if native_files_supported() {
 ```
 </details>
 
+<details><summary>file runtime state dump 示例</summary>
+
+```moonbit
+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 => ()
+}
+```
+</details>
+
 ## 📂 仓库结构
 
 - `bitlogger/`：MoonBit 库 package，本体实现、测试与 Mooncake README
@@ -230,6 +249,7 @@ if native_files_supported() {
 - `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 计数
+- `file_sink_state_to_json(...)`、`stringify_file_sink_state(...)`、`runtime_file_state_to_json(...)`、`stringify_runtime_file_state(...)` 可直接把 file / queued-file 快照导出为 JSON，便于排障或上报
 - `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 009509f..4013790 100644
--- a/bitlogger/BitLogger_test.mbt
+++ b/bitlogger/BitLogger_test.mbt
@@ -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(
diff --git a/bitlogger/README.mbt.md b/bitlogger/README.mbt.md
index 763c364..3263bc5 100644
--- a/bitlogger/README.mbt.md
+++ b/bitlogger/README.mbt.md
@@ -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 与失败计数访问器
diff --git a/bitlogger/config.mbt b/bitlogger/config.mbt
index 97fa3fa..3177a41 100644
--- a/bitlogger/config.mbt
+++ b/bitlogger/config.mbt
@@ -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
   }
 }
diff --git a/bitlogger/sinks.mbt b/bitlogger/sinks.mbt
index ecda0c3..93ed258 100644
--- a/bitlogger/sinks.mbt
+++ b/bitlogger/sinks.mbt
@@ -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 },
diff --git a/docs/README-en.md b/docs/README-en.md
index 586196e..aac3917 100644
--- a/docs/README-en.md
+++ b/docs/README-en.md
@@ -191,6 +191,24 @@ if native_files_supported() {
 }
 ```
 
+File runtime state dump:
+
+```moonbit
+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 => ()
+}
+```
+
 ## Repository Layout
 
 - `bitlogger/`: MoonBit library package, tests, and Mooncake package README
@@ -215,6 +233,7 @@ if native_files_supported() {
 - `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.
+- `file_sink_state_to_json(...)`, `stringify_file_sink_state(...)`, `runtime_file_state_to_json(...)`, and `stringify_runtime_file_state(...)` can export file and queued-file snapshots directly as JSON for diagnostics or reporting.
 - `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 4ff8030..aa4f7c7 100644
--- a/docs/changes/0.3.0.md
+++ b/docs/changes/0.3.0.md
@@ -41,6 +41,7 @@ version 0.3.0
 - 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 `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