From 1ebf31945c05b3c6b7f8a5d37dcb01da493e609a Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 22:38:14 +0800 Subject: [PATCH] :memo: document runtime sink state surface --- docs/api/index.md | 3 + docs/api/runtime-sink-dropped-count.md | 76 +++++++++++++++++++++++ docs/api/runtime-sink-pending-count.md | 75 +++++++++++++++++++++++ docs/api/runtime-sink.md | 85 ++++++++++++++++++++++++++ 4 files changed, 239 insertions(+) create mode 100644 docs/api/runtime-sink-dropped-count.md create mode 100644 docs/api/runtime-sink-pending-count.md create mode 100644 docs/api/runtime-sink.md diff --git a/docs/api/index.md b/docs/api/index.md index aa259bf..3c4bcd9 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -342,9 +342,12 @@ BitLogger API navigation. ## Configured logger runtime +- [runtime-sink.md](./runtime-sink.md) - [runtime-sink-flush.md](./runtime-sink-flush.md) - [runtime-sink-drain.md](./runtime-sink-drain.md) - [runtime-sink-close.md](./runtime-sink-close.md) +- [runtime-sink-pending-count.md](./runtime-sink-pending-count.md) +- [runtime-sink-dropped-count.md](./runtime-sink-dropped-count.md) - [configured-logger.md](./configured-logger.md) - [configured-logger-flush.md](./configured-logger-flush.md) - [configured-logger-drain.md](./configured-logger-drain.md) diff --git a/docs/api/runtime-sink-dropped-count.md b/docs/api/runtime-sink-dropped-count.md new file mode 100644 index 0000000..233f4aa --- /dev/null +++ b/docs/api/runtime-sink-dropped-count.md @@ -0,0 +1,76 @@ +--- +name: runtime-sink-dropped-count +group: api +category: runtime +update-time: 20260613 +description: Read the cumulative dropped-record count from a RuntimeSink. +key-word: + - runtime + - sink + - queue + - public +--- + +## Runtime-sink-dropped-count + +Read the cumulative dropped-record count from a `RuntimeSink`. This helper exposes the direct sink-level loss metric for queue-backed runtime variants. + +### Interface + +```moonbit +pub fn RuntimeSink::dropped_count(self : RuntimeSink) -> Int { +``` + +#### input + +- `self : RuntimeSink` - Runtime sink 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-wrapped runtime variants forward to the wrapped queue sink's `dropped_count()` value. +- Plain console and plain file runtime variants return `0` because they do not track queued record drops. +- The counter is cumulative for the lifetime of the concrete runtime sink value. +- This method is the direct sink-level API used by `ConfiguredLogger::dropped_count(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Queue Loss Visibility + +When a runtime sink may discard records under pressure: +```moonbit +if sink.dropped_count() > 0 { + println("runtime sink dropped records") +} +``` + +In this example, direct runtime queue loss becomes visible without inspecting inner fields manually. + +#### When Compare Queue Tuning Changes + +When queue overflow behavior should be checked operationally: +```moonbit +ignore(sink.dropped_count()) +``` + +In this example, the helper exposes the metric needed to compare different queue settings. + +### Error Case + +e.g.: +- If the runtime sink is not queue-backed, the method simply returns `0`. + +- If callers need the higher-level logger wrapper API, use `ConfiguredLogger::dropped_count()` instead. + +### 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/runtime-sink-pending-count.md b/docs/api/runtime-sink-pending-count.md new file mode 100644 index 0000000..581c685 --- /dev/null +++ b/docs/api/runtime-sink-pending-count.md @@ -0,0 +1,75 @@ +--- +name: runtime-sink-pending-count +group: api +category: runtime +update-time: 20260613 +description: Read the current queued backlog count from a RuntimeSink. +key-word: + - runtime + - sink + - queue + - public +--- + +## Runtime-sink-pending-count + +Read the current queued backlog count from a `RuntimeSink`. This is the direct sink-level queue metric behind configured logger pending-count behavior. + +### Interface + +```moonbit +pub fn RuntimeSink::pending_count(self : RuntimeSink) -> Int { +``` + +#### input + +- `self : RuntimeSink` - Runtime sink whose current queue backlog should be inspected. + +#### output + +- `Int` - Current number of pending queued records. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- Queue-wrapped runtime variants forward to the wrapped queue sink's `pending_count()` value. +- Plain console and plain file runtime variants return `0` because they do not own a pending queue here. +- This is a point-in-time metric and may change immediately after it is read. +- This method is the direct sink-level API used by `ConfiguredLogger::pending_count(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Direct Queue Backlog Visibility + +When code is working with a `RuntimeSink` value directly and wants queue pressure information: +```moonbit +let pending = sink.pending_count() +``` + +In this example, backlog is read from the runtime sink without going through a logger wrapper. + +#### When Verify Manual Drain Progress + +When drain loops should observe remaining queue backlog directly: +```moonbit +ignore(sink.drain(max_items=8)) +ignore(sink.pending_count()) +``` + +In this example, the metric helps confirm whether manual queue draining reduced backlog. + +### Error Case + +e.g.: +- If the runtime sink is not queue-backed, the method simply returns `0`. + +- If callers need the higher-level logger wrapper API, use `ConfiguredLogger::pending_count()` instead. + +### Notes + +1. Use this helper for simple direct queue visibility on `RuntimeSink` values. + +2. Pair it with `dropped_count()` when investigating queue pressure and loss. diff --git a/docs/api/runtime-sink.md b/docs/api/runtime-sink.md new file mode 100644 index 0000000..dc01aeb --- /dev/null +++ b/docs/api/runtime-sink.md @@ -0,0 +1,85 @@ +--- +name: runtime-sink +group: api +category: runtime +update-time: 20260613 +description: Public runtime sink enum used by config-built synchronous loggers to unify console, file, and queued sink variants. +key-word: + - runtime + - sink + - type + - public +--- + +## Runtime-sink + +`RuntimeSink` is the public runtime sink enum used by config-built synchronous loggers. It unifies console, file, and queued sink variants behind one runtime-facing sink surface. + +### Interface + +```moonbit +pub(all) enum RuntimeSink { + Console(ConsoleSink) + JsonConsole(JsonConsoleSink) + TextConsole(FormattedConsoleSink) + File(FileSink) + QueuedConsole(QueuedSink[ConsoleSink]) + QueuedJsonConsole(QueuedSink[JsonConsoleSink]) + QueuedTextConsole(QueuedSink[FormattedConsoleSink]) + QueuedFile(QueuedSink[FileSink]) +} +``` + +#### output + +- `RuntimeSink` - Public runtime sink union used by `ConfiguredLogger` and config-built logging helpers. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public enum root type, not a type alias. +- The variants cover plain console sinks, plain file sinks, and queue-wrapped forms of those sink families. +- `build_logger(...)` and related config-driven construction paths use this type as the concrete sink behind `ConfiguredLogger`. +- The type exposes direct runtime helpers such as `flush()`, `drain()`, `close()`, `pending_count()`, and `dropped_count()`. +- Queue-specific metrics are meaningful only for queued variants, while plain variants usually report `0` for queue counters. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Config-built Runtime Sink Surface + +When code should keep the runtime sink union explicit after config assembly: +```moonbit +let logger = build_logger(LoggerConfig::new(target="svc")) +let sink : RuntimeSink = logger.sink +``` + +In this example, the concrete runtime sink remains available for direct runtime inspection. + +#### When Need Direct Runtime Variant-specific Branching + +When behavior should differ between plain and queued runtime sink variants: +```moonbit +match sink { + QueuedFile(inner) => ignore(inner.pending_count()) + File(inner) => ignore(inner.is_available()) + _ => () +} +``` + +In this example, the enum shape makes runtime sink-specific handling explicit. + +### Error Case + +e.g.: +- `RuntimeSink` itself does not have a runtime failure mode. + +- Actual file behavior, queue backlog, and close results still depend on the active variant and current backend state. + +### Notes + +1. `ConfiguredLogger` is the main higher-level alias that wraps `Logger[RuntimeSink]`. + +2. Use the direct `RuntimeSink` helpers when code owns the sink value itself instead of only the logger wrapper.