From 0ab3b9595929fa8e99fbf2866befe02cc3cce960 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 14:18:54 +0800 Subject: [PATCH] :memo: Add configured logger file runtime API docs --- docs/api/configured-logger-file-available.md | 76 ++++++++++++++++++ docs/api/configured-logger-file-close.md | 74 ++++++++++++++++++ docs/api/configured-logger-file-flush.md | 74 ++++++++++++++++++ docs/api/configured-logger-file-path.md | 74 ++++++++++++++++++ docs/api/configured-logger-file-reopen.md | 75 ++++++++++++++++++ .../configured-logger-file-runtime-state.md | 77 +++++++++++++++++++ 6 files changed, 450 insertions(+) create mode 100644 docs/api/configured-logger-file-available.md create mode 100644 docs/api/configured-logger-file-close.md create mode 100644 docs/api/configured-logger-file-flush.md create mode 100644 docs/api/configured-logger-file-path.md create mode 100644 docs/api/configured-logger-file-reopen.md create mode 100644 docs/api/configured-logger-file-runtime-state.md diff --git a/docs/api/configured-logger-file-available.md b/docs/api/configured-logger-file-available.md new file mode 100644 index 0000000..f3c41df --- /dev/null +++ b/docs/api/configured-logger-file-available.md @@ -0,0 +1,76 @@ +--- +name: configured-logger-file-available +group: api +category: runtime +update-time: 20260512 +description: Read whether the configured runtime logger currently has an available file sink behind its runtime sink shape. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-available + +Read whether a `ConfiguredLogger` currently has an available file sink. This helper is useful for runtime diagnostics and recovery checks after config-driven file logger construction. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_available(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink availability should be inspected. + +#### output + +- `Bool` - Whether an underlying file sink is available. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed runtime sinks report actual file availability. +- Non-file sinks report `false`. +- Queued file sinks still expose the availability of their wrapped file sink. +- This helper delegates to the runtime sink and does not mutate logger state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime File Health Checks + +When operators or code should check file sink readiness: +```moonbit +if !logger.file_available() { + println("file sink unavailable") +} +``` + +In this example, the configured logger exposes file health directly. + +#### When Gate Recovery Logic + +When reopen or fallback behavior depends on file availability: +```moonbit +let ok = logger.file_available() +``` + +In this example, callers can decide whether a recovery action is needed. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers need detailed failure counters rather than a simple availability flag, `file_state()` or `file_runtime_state()` is the better API. + +### Notes + +1. Use this helper for lightweight file sink health checks. + +2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems. diff --git a/docs/api/configured-logger-file-close.md b/docs/api/configured-logger-file-close.md new file mode 100644 index 0000000..ce3df91 --- /dev/null +++ b/docs/api/configured-logger-file-close.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-close +group: api +category: runtime +update-time: 20260512 +description: Close the file sink behind a configured runtime logger when one is present. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-close + +Close the file sink behind a `ConfiguredLogger`. This helper is the file-specific runtime close surface for config-built file loggers. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_close(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be closed. + +#### output + +- `Bool` - Whether the underlying file close succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks forward directly to file close behavior. +- Queued file sinks flush queue work before closing the wrapped file sink. +- Non-file sinks return `false`. +- This helper is narrower than generic `close()` because it specifically targets file sink shutdown. + +### How to Use + +Here are some specific examples provided. + +#### When Need File-specific Runtime Teardown + +When a config-built file logger should close its file handle explicitly: +```moonbit +ignore(logger.file_close()) +``` + +In this example, file teardown happens through the configured logger facade. + +#### When Need A File-specific Close Result + +When application code wants the file close outcome directly: +```moonbit +let closed = logger.file_close() +``` + +In this example, the result describes file close behavior rather than generic sink close behavior. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers only need generic sink teardown, `close()` is the broader API. + +### Notes + +1. Prefer this helper when file-backed runtime behavior matters specifically. + +2. Queued file sinks may flush pending records before closing the file. diff --git a/docs/api/configured-logger-file-flush.md b/docs/api/configured-logger-file-flush.md new file mode 100644 index 0000000..0877537 --- /dev/null +++ b/docs/api/configured-logger-file-flush.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-flush +group: api +category: runtime +update-time: 20260512 +description: Flush the file sink behind a configured runtime logger when one is present. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-flush + +Flush the file sink behind a `ConfiguredLogger`. This helper is the file-specific runtime flush surface for config-built file loggers. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_flush(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be flushed. + +#### output + +- `Bool` - Whether the underlying file flush succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks forward directly to file flush behavior. +- Queued file sinks first flush queued records, then flush the wrapped file sink. +- Non-file sinks return `false`. +- This helper is narrower than generic `flush()` because it targets file sink behavior specifically. + +### How to Use + +Here are some specific examples provided. + +#### When Need Explicit File Durability Steps + +When a config-built file logger should flush to disk explicitly: +```moonbit +ignore(logger.file_flush()) +``` + +In this example, the file-backed runtime sink is flushed directly through the configured logger. + +#### When Need A File-specific Success Flag + +When code should branch on the outcome of a file flush: +```moonbit +let ok = logger.file_flush() +``` + +In this example, callers can distinguish file flush success from a non-file sink shape. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers want generic queue or sink advancement instead of file-specific behavior, `flush()` is the broader API. + +### Notes + +1. Prefer this helper when the configured sink is known to be file-backed. + +2. Queued file sinks may perform both queue flush and file flush work here. diff --git a/docs/api/configured-logger-file-path.md b/docs/api/configured-logger-file-path.md new file mode 100644 index 0000000..9cec8f1 --- /dev/null +++ b/docs/api/configured-logger-file-path.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-file-path +group: api +category: runtime +update-time: 20260512 +description: Read the effective file path used by the configured runtime logger when it is file-backed. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-path + +Read the effective file path used by a `ConfiguredLogger`. This helper is useful for diagnostics, support output, and confirming which file-backed runtime sink is active. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_path(self : ConfiguredLogger) -> String {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file path should be inspected. + +#### output + +- `String` - Effective runtime file path, or an empty string for non-file sinks. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks return their current file path. +- Queued file sinks forward the wrapped file sink path. +- Non-file sinks return an empty string. +- This helper is observation-only and does not modify file state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Path Diagnostics + +When diagnostics should show which file is active: +```moonbit +println(logger.file_path()) +``` + +In this example, operators can verify the effective destination path directly. + +#### When Build Support Output + +When application state dumps should include file destination info: +```moonbit +let path = logger.file_path() +``` + +In this example, the path can be surfaced without reading broader runtime state. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns an empty string. + +- If callers need richer file status than just the path, `file_state()` or `file_runtime_state()` is the better API. + +### Notes + +1. Use this helper for direct runtime path visibility. + +2. Empty string usually means the configured sink is not file-backed. diff --git a/docs/api/configured-logger-file-reopen.md b/docs/api/configured-logger-file-reopen.md new file mode 100644 index 0000000..d655331 --- /dev/null +++ b/docs/api/configured-logger-file-reopen.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-file-reopen +group: api +category: runtime +update-time: 20260512 +description: Reopen the file sink behind a configured runtime logger with an optional append-mode override. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-reopen + +Reopen the file sink behind a `ConfiguredLogger`. This helper is useful for recovery flows after file unavailability or policy changes. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_reopen(self : ConfiguredLogger, append~ : Bool? = None) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened. +- `append : Bool?` - Optional append-mode override used for reopen behavior. + +#### output + +- `Bool` - Whether reopen succeeded. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Plain file sinks reopen directly. +- Queued file sinks forward reopen behavior to the wrapped file sink. +- `append=None` preserves current reopen policy, while `Some(true/false)` overrides append mode. +- Non-file sinks return `false`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Recovery After File Failure + +When application code should attempt to restore file logging: +```moonbit +ignore(logger.file_reopen()) +``` + +In this example, the configured logger tries to reopen its runtime file sink using current policy. + +#### When Need Explicit Append-mode Reopen + +When recovery should choose append or truncate behavior explicitly: +```moonbit +let ok = logger.file_reopen(append=Some(true)) +``` + +In this example, reopen behavior is directed by the call site. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `false`. + +- If callers only need the current configured policy, `file_reopen_with_current_policy()` may be the clearer API. + +### Notes + +1. Use this helper for explicit recovery flows. + +2. Pair it with `file_available()` and failure counters when diagnosing reopen behavior. diff --git a/docs/api/configured-logger-file-runtime-state.md b/docs/api/configured-logger-file-runtime-state.md new file mode 100644 index 0000000..577db4f --- /dev/null +++ b/docs/api/configured-logger-file-runtime-state.md @@ -0,0 +1,77 @@ +--- +name: configured-logger-file-runtime-state +group: api +category: runtime +update-time: 20260512 +description: Read combined file and queue runtime state from a configured logger when it is backed by a file sink. +key-word: + - logger + - runtime + - file + - public +--- + +## Configured-logger-file-runtime-state + +Read combined file and queue runtime state from a `ConfiguredLogger`. This helper is the richest file-specific diagnostics API on config-built runtime loggers. + +### Interface + +```moonbit +pub fn ConfiguredLogger::file_runtime_state(self : ConfiguredLogger) -> RuntimeFileState? {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose file runtime state should be inspected. + +#### output + +- `RuntimeFileState?` - Combined file and queue diagnostics when the runtime sink is file-backed, otherwise `None`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- File-backed sinks return `Some(RuntimeFileState)`. +- Queued file sinks include both file status and queue metrics in the returned state. +- Non-file sinks return `None`. +- This helper is richer than `file_state()` because it can also surface queued backlog and dropped counts. + +### How to Use + +Here are some specific examples provided. + +#### When Need Rich File Runtime Diagnostics + +When support output should include both file and queue state: +```moonbit +let state = logger.file_runtime_state() +``` + +In this example, callers can inspect availability, failure counters, and queue metrics together. + +#### When Need To Branch On File-backed Runtime Shape + +When code should behave differently for file-backed config-built loggers: +```moonbit +match logger.file_runtime_state() { + Some(state) => ignore(state) + None => () +} +``` + +In this example, the optional return value reflects whether the runtime sink is file-backed. + +### Error Case + +e.g.: +- If the configured sink is not file-backed, the method returns `None`. + +- If callers only need raw file status without queue context, `file_state()` may be the simpler API. + +### Notes + +1. Use this helper for the richest file-backed runtime diagnostics on config-built loggers. + +2. It is especially useful for queued file sinks where file health and queue state both matter.