From 911dcd840cce3ddd2bede41b807efff6312422a7 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:43:50 +0800 Subject: [PATCH] :memo: align async logger state docs --- docs/api/async-logger-state-new.md | 9 +++++++-- docs/api/async-logger-state-to-json.md | 14 ++++++++++---- docs/api/async-logger-state-type.md | 9 +++++++-- docs/api/async-logger-state.md | 9 +++++++-- docs/api/stringify-async-logger-state.md | 11 +++++++++-- 5 files changed, 40 insertions(+), 12 deletions(-) diff --git a/docs/api/async-logger-state-new.md b/docs/api/async-logger-state-new.md index 2a82dc4..b3afd5c 100644 --- a/docs/api/async-logger-state-new.md +++ b/docs/api/async-logger-state-new.md @@ -2,8 +2,8 @@ name: async-logger-state-new group: api category: async -update-time: 20260613 -description: Construct an AsyncLoggerState snapshot from explicit runtime, queue, lifecycle, and failure values. +update-time: 20260614 +description: Construct an AsyncLoggerState snapshot from explicit runtime, queue, lifecycle, failure, and flush-policy values without probing a live logger. key-word: - async - logger @@ -52,6 +52,7 @@ Detailed rules explaining key parameters and behaviors - This constructor simply packages the supplied fields into one public snapshot value. - It does not inspect a live logger instance by itself. - `AsyncLogger::state()` is the higher-level API that reads these values from a concrete logger. +- It also does not validate whether the supplied fields represent a combination that could come from one real logger instant. - The constructed value matches the same public shape used by async logger serializers. ### How to Use @@ -101,8 +102,12 @@ e.g.: - If callers want a snapshot directly from one live logger instance, `AsyncLogger::state()` is the simpler API. +- If callers manually combine a runtime snapshot, counters, or flush policy that do not actually belong together, the constructor still accepts that synthetic snapshot. + ### Notes 1. Use this helper when code should construct an `AsyncLoggerState` value explicitly. 2. Pair it with `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when the snapshot should be exported. + +3. Prefer `AsyncLogger::state()` when the goal is to report the actual current state of one live logger instance. diff --git a/docs/api/async-logger-state-to-json.md b/docs/api/async-logger-state-to-json.md index 35778f5..0387bbd 100644 --- a/docs/api/async-logger-state-to-json.md +++ b/docs/api/async-logger-state-to-json.md @@ -2,8 +2,8 @@ name: async-logger-state-to-json group: api category: async -update-time: 20260512 -description: Convert an AsyncLoggerState snapshot into a JSON value for diagnostics and transport. +update-time: 20260614 +description: Convert an AsyncLoggerState snapshot into a JSON value for diagnostics and transport using the canonical nested runtime shape and flush-policy labels. key-word: - async - state @@ -34,6 +34,8 @@ pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.Json Detailed rules explaining key parameters and behaviors - The JSON includes runtime mode, worker support, queue counters, lifecycle flags, last error, and flush policy. +- The top-level fields are `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`. +- The nested `runtime` field reuses `async_runtime_state_to_json(...)`, and `flush_policy` is serialized with the canonical labels `Never`, `Batch`, or `Shutdown`. - This helper is suitable for health endpoints, diagnostics payloads, and custom serialization flows. - It shares the same stable field names used by `stringify_async_logger_state(...)`. - The state must already have been captured before serialization. @@ -70,7 +72,11 @@ e.g.: ### Notes -1. Use this API when downstream code wants a JSON value rather than a ready-made string. +1. This helper preserves the nested runtime snapshot instead of flattening `mode` and `background_worker` onto the top level. -2. Pair it with `AsyncLogger::state()` to capture the snapshot first. +2. The resulting object matches the compact string form produced by `stringify_async_logger_state(...)` after JSON stringification. + +3. Use this API when downstream code wants a JSON value rather than a ready-made string. + +4. Pair it with `AsyncLogger::state()` to capture the snapshot first. diff --git a/docs/api/async-logger-state-type.md b/docs/api/async-logger-state-type.md index d6d42d5..5ab70ac 100644 --- a/docs/api/async-logger-state-type.md +++ b/docs/api/async-logger-state-type.md @@ -2,8 +2,8 @@ name: async-logger-state-type group: api category: async -update-time: 20260613 -description: Public async logger state alias used for queue, lifecycle, and runtime diagnostics. +update-time: 20260614 +description: Public async logger state alias used for queue, lifecycle, runtime, and flush-policy diagnostics. key-word: - async - logger @@ -33,6 +33,7 @@ Detailed rules explaining key parameters and behaviors - The `runtime` field embeds an `AsyncRuntimeState` snapshot. - The remaining fields capture queue counts, lifecycle status, failure state, last error text, and active flush policy. - `AsyncLogger::state()` returns this type directly, while `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` export the same data shape for diagnostics. +- `AsyncLogger::state()` currently builds this snapshot from `async_runtime_state()` plus the logger's current counters, lifecycle flags, last error, and flush policy. ### How to Use @@ -66,8 +67,12 @@ e.g.: - `last_error` may be an empty string when no failure has occurred, which is normal and not a special error condition by itself. +- Because this is just a data shape, manual construction can represent combinations that do not come from a live logger at one exact instant. + ### Notes 1. Use `AsyncLogger::state()` when you need a value of this type from one logger instance. 2. Use `AsyncRuntimeState` when only backend-level capability information is needed and logger-instance state is unnecessary. + +3. Use `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when this snapshot should leave typed space and become stable diagnostic output. diff --git a/docs/api/async-logger-state.md b/docs/api/async-logger-state.md index c02c17d..7ff3697 100644 --- a/docs/api/async-logger-state.md +++ b/docs/api/async-logger-state.md @@ -2,8 +2,8 @@ name: async-logger-state group: api category: async -update-time: 20260512 -description: Read a full async logger runtime snapshot including queue counters, lifecycle flags, and runtime mode. +update-time: 20260614 +description: Read a full async logger runtime snapshot including the embedded runtime snapshot, queue counters, lifecycle flags, last error, and flush policy. key-word: - async - state @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - `AsyncLoggerState` includes `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`. - `state()` returns a point-in-time snapshot rather than a live handle. +- This helper is equivalent to `AsyncLoggerState::new(async_runtime_state(), self.pending_count(), self.dropped_count(), self.is_closed(), self.is_running(), self.has_failed(), self.last_error(), self.flush_policy())`. - `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` convert the snapshot to stable diagnostic output. - `runtime` embeds the result of `async_runtime_state()` so callers do not need to join separate helpers manually. @@ -73,8 +74,12 @@ e.g.: - If the queue is empty, `pending_count` is `0`; this is normal and not a special error condition. +- `flush_policy` reports the logger's configured async flush mode, not whether a flush has already happened. + ### Notes 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers. 2. Use `pretty=true` when emitting logs for humans and the compact form for machine-oriented payloads. + +3. Use `AsyncLoggerState::new(...)` only when tests or adapters need to construct a manual snapshot instead of reading one directly from a logger instance. diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md index c87d6cb..e5ec0e4 100644 --- a/docs/api/stringify-async-logger-state.md +++ b/docs/api/stringify-async-logger-state.md @@ -2,8 +2,8 @@ name: stringify-async-logger-state group: api category: async -update-time: 20260512 -description: Serialize AsyncLoggerState into compact or pretty JSON text for logs and diagnostics. +update-time: 20260614 +description: Serialize AsyncLoggerState into compact or pretty JSON text for logs and diagnostics using the canonical nested runtime snapshot shape. key-word: - async - stringify @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON. - `pretty=true` returns indented JSON suitable for human diagnostics. - This helper is built on top of `async_logger_state_to_json(...)`. +- The compact form matches snapshots such as `{"runtime":{"mode":"native_worker","background_worker":true},"pending_count":0,...}`. - String output is convenient for logs, CLI output, and startup diagnostics. ### How to Use @@ -71,3 +72,9 @@ e.g.: - If callers need a JSON value instead of text, they should use `async_logger_state_to_json(...)` instead. +### Notes + +1. The nested `runtime` section uses the same canonical mode labels as `stringify_async_runtime_state(...)`. + +2. The compact output shape is already locked by the async runtime snapshot tests, so it is suitable for stable diagnostics and assertions. +