diff --git a/docs/api/configured-logger-close.md b/docs/api/configured-logger-close.md new file mode 100644 index 0000000..7517139 --- /dev/null +++ b/docs/api/configured-logger-close.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-close +group: api +category: runtime +update-time: 20260512 +description: Close the configured runtime logger sink and return whether the underlying sink reported a close action. +key-word: + - logger + - runtime + - lifecycle + - public +--- + +## Configured-logger-close + +Close the sink behind a `ConfiguredLogger`. This helper is the config-driven runtime close surface for queue-backed or file-backed sinks. + +### Interface + +```moonbit +pub fn ConfiguredLogger::close(self : ConfiguredLogger) -> Bool {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose sink should be closed. + +#### output + +- `Bool` - Whether the underlying runtime sink reported a successful close action. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-backed file sinks close the wrapped file sink. +- Plain file sinks forward directly to file close behavior. +- Console-style sinks usually report `true` because they do not have a meaningful close step. +- This helper delegates to `RuntimeSink::close(...)` through the configured logger wrapper. + +### How to Use + +Here are some specific examples provided. + +#### When Need Config-driven Runtime Teardown + +When a config-built logger should release its sink resources: +```moonbit +ignore(logger.close()) +``` + +In this example, sink teardown happens through the configured logger facade. + +#### When Need To Observe Close Outcome + +When application code wants a success flag from runtime close behavior: +```moonbit +let closed = logger.close() +``` + +In this example, callers can branch on the reported close result. + +### Error Case + +e.g.: +- If the runtime sink has no real close action, the helper may still return `true` as a no-op success. + +- If callers need a file-specific close path with queue flush nuances, `file_close()` may be the better API. + +### Notes + +1. This is the generic configured runtime close helper. + +2. Prefer file-specific helpers when the sink shape is known to be file-backed. diff --git a/docs/api/configured-logger-drain.md b/docs/api/configured-logger-drain.md new file mode 100644 index 0000000..ef64248 --- /dev/null +++ b/docs/api/configured-logger-drain.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-drain +group: api +category: runtime +update-time: 20260512 +description: Drain queued work from a configured runtime logger with optional item limits. +key-word: + - logger + - runtime + - queue + - public +--- + +## Configured-logger-drain + +Drain queued work from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping should be advanced in a controlled, bounded way. + +### Interface + +```moonbit +pub fn ConfiguredLogger::drain(self : ConfiguredLogger, max_items~ : Int = -1) -> Int {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose queued work should be drained. +- `max_items : Int` - Optional upper bound on how many queued items to drain. Negative values mean no explicit bound. + +#### output + +- `Int` - Number of drained items. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-wrapped sinks may drain up to `max_items` records. +- For plain file sinks, the runtime falls back to file flush behavior instead of queue draining. +- For sinks without queue semantics, the result is typically `0`. +- This helper delegates to `RuntimeSink::drain(...)` through the configured logger wrapper. + +### How to Use + +Here are some specific examples provided. + +#### When Need Bounded Queue Progress + +When queued output should be advanced in chunks: +```moonbit +let drained = logger.drain(max_items=16) +``` + +In this example, callers limit how much queued work is processed in one step. + +#### When Need Full Manual Drain + +When the configured queue should be emptied explicitly: +```moonbit +ignore(logger.drain()) +``` + +In this example, the configured runtime logger drains without imposing an item cap. + +### Error Case + +e.g.: +- If the runtime sink is not queue-backed, draining may return `0` or follow fallback flush behavior. + +- If callers only need generic flush semantics, `flush()` may be the simpler API. + +### Notes + +1. Prefer this helper when queue progress should be bounded or observable. + +2. Use `pending_count()` to inspect remaining backlog after the drain call. diff --git a/docs/api/configured-logger-dropped-count.md b/docs/api/configured-logger-dropped-count.md new file mode 100644 index 0000000..872bc81 --- /dev/null +++ b/docs/api/configured-logger-dropped-count.md @@ -0,0 +1,76 @@ +--- +name: configured-logger-dropped-count +group: api +category: runtime +update-time: 20260512 +description: Read the cumulative dropped-record count from a configured runtime logger. +key-word: + - logger + - runtime + - queue + - public +--- + +## Configured-logger-dropped-count + +Read the cumulative dropped-record count from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping may discard records under pressure. + +### Interface + +```moonbit +pub fn ConfiguredLogger::dropped_count(self : ConfiguredLogger) -> Int {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose dropped-record metric should be inspected. + +#### output + +- `Int` - Number of dropped records reported by the runtime sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-backed sinks return their live dropped-count metric. +- Non-queued sinks report `0`. +- The counter is cumulative for the runtime sink lifetime. +- This helper delegates to `RuntimeSink::dropped_count(...)` through the configured logger wrapper. + +### How to Use + +Here are some specific examples provided. + +#### When Need Loss Visibility On Config-built Queues + +When a config-driven queue may discard records: +```moonbit +if logger.dropped_count() > 0 { + println("configured logger dropped records") +} +``` + +In this example, the runtime logger exposes queue loss without manual sink inspection. + +#### When Compare Queue Tuning Changes + +When queue overflow policy should be validated operationally: +```moonbit +ignore(logger.dropped_count()) +``` + +In this example, the helper exposes the metric needed to compare runtime queue tuning. + +### Error Case + +e.g.: +- If the logger is not queue-backed, the method simply returns `0`. + +- If callers need queue shape and file status together, `file_runtime_state()` may carry more useful context for file sinks. + +### Notes + +1. This helper reports cumulative loss, not the reason for that loss. + +2. Pair it with `pending_count()` and queue configuration when investigating pressure. diff --git a/docs/api/configured-logger-flush.md b/docs/api/configured-logger-flush.md new file mode 100644 index 0000000..49a09e9 --- /dev/null +++ b/docs/api/configured-logger-flush.md @@ -0,0 +1,74 @@ +--- +name: configured-logger-flush +group: api +category: runtime +update-time: 20260512 +description: Flush a configured runtime logger and return how many queued or file-backed operations were advanced. +key-word: + - logger + - runtime + - flush + - public +--- + +## Configured-logger-flush + +Flush a `ConfiguredLogger` and return how much work was advanced. This is the main runtime helper for forcing queued or file-backed logger output to move forward after config-driven construction. + +### Interface + +```moonbit +pub fn ConfiguredLogger::flush(self : ConfiguredLogger) -> Int {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose sink should be flushed. + +#### output + +- `Int` - Count of flushed or drained items as reported by the runtime sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- For queue-wrapped sinks, this forwards to the queue drain/flush behavior. +- For plain file sinks, the return value reflects whether a file flush happened. +- For plain console-style sinks, the result is typically `0` because there is no meaningful buffered flush step. +- This helper delegates to `RuntimeSink::flush(...)` through the configured logger wrapper. + +### How to Use + +Here are some specific examples provided. + +#### When Need Explicit Queue Progress + +When config-built queue output should be advanced manually: +```moonbit +ignore(logger.flush()) +``` + +In this example, the configured runtime logger is flushed without reaching into the sink directly. + +#### When Need A Post-write Flush Barrier + +When a service wants stronger delivery behavior after a burst of writes: +```moonbit +let flushed = logger.flush() +``` + +In this example, callers can observe how much work was advanced by the flush request. + +### Error Case + +e.g.: +- If the configured sink has no flushable buffering, the method may simply return `0`. + +- If callers need bounded manual draining rather than generic flush behavior, `drain(...)` is the better API. + +### Notes + +1. Use this helper after config-driven logger construction when explicit runtime flushing matters. + +2. The exact return value depends on the underlying runtime sink shape. diff --git a/docs/api/configured-logger-pending-count.md b/docs/api/configured-logger-pending-count.md new file mode 100644 index 0000000..24b73f9 --- /dev/null +++ b/docs/api/configured-logger-pending-count.md @@ -0,0 +1,75 @@ +--- +name: configured-logger-pending-count +group: api +category: runtime +update-time: 20260512 +description: Read the current queued backlog count from a configured runtime logger. +key-word: + - logger + - runtime + - queue + - public +--- + +## Configured-logger-pending-count + +Read the current queued backlog count from a `ConfiguredLogger`. This is the direct runtime metric for config-driven queue wrapping. + +### Interface + +```moonbit +pub fn ConfiguredLogger::pending_count(self : ConfiguredLogger) -> Int {} +``` + +#### input + +- `self : ConfiguredLogger` - Config-driven runtime logger whose queue backlog should be inspected. + +#### output + +- `Int` - Current number of pending queued records. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-backed sinks return their live pending count. +- Non-queued sinks report `0`. +- This is a point-in-time metric and may change immediately after it is read. +- This helper delegates to `RuntimeSink::pending_count(...)` through the configured logger wrapper. + +### How to Use + +Here are some specific examples provided. + +#### When Need Configured Queue Backlog Visibility + +When a config-built logger should expose queue pressure: +```moonbit +let pending = logger.pending_count() +``` + +In this example, queue backlog is observed without reaching into the sink internals. + +#### When Verify Manual Drain Progress + +When drain loops should observe remaining backlog: +```moonbit +ignore(logger.drain(max_items=8)) +ignore(logger.pending_count()) +``` + +In this example, the queue metric helps verify manual drain progress. + +### Error Case + +e.g.: +- If the logger is not queue-backed, the method simply returns `0`. + +- If callers need richer file-plus-queue state for file sinks, `file_runtime_state()` is the better API. + +### Notes + +1. Use this helper for simple queue visibility on config-built loggers. + +2. Pair it with `dropped_count()` when investigating loss behavior.