mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 refine library logger write docs
This commit is contained in:
Nanaloveyuki
@@ -3,7 +3,7 @@ name: library-logger-error
|
||||
group: api
|
||||
category: facade
|
||||
update-time: 20260613
|
||||
description: Emit an error-level record through a LibraryLogger facade using the highest built-in severity shortcut.
|
||||
description: Emit an error-level record through a LibraryLogger facade by delegating to the wrapped logger's error shortcut.
|
||||
key-word:
|
||||
- library
|
||||
- facade
|
||||
@@ -39,10 +39,11 @@ pub fn[S : Sink] LibraryLogger::error(
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper delegates to `log(Level::Error, ...)` on the wrapped logger.
|
||||
- This helper delegates to `error(...)` on the wrapped logger, which in turn uses `log(Level::Error, ...)`.
|
||||
- `Error` is the highest built-in severity in this sync facade API.
|
||||
- Per-call target override is not exposed here; use `log(...)` when explicit target control is required.
|
||||
- Sink composition, filtering, patching, and queue wrappers still apply normally.
|
||||
- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first.
|
||||
|
||||
### How to Use
|
||||
|
||||
@@ -66,6 +67,8 @@ logger.error("dispatch failed", fields=[field("job_id", "42")])
|
||||
|
||||
In this example, the record carries machine-readable context without dropping to the generic `log(...)` form.
|
||||
|
||||
And any shared context already carried by the facade still participates through the wrapped logger pipeline.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
@@ -73,8 +76,12 @@ e.g.:
|
||||
|
||||
- If a target override is required, use `log(...)` instead of this severity shortcut.
|
||||
|
||||
- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for high-severity library failures.
|
||||
|
||||
2. Emitting an error record is separate from throwing or handling program exceptions.
|
||||
|
||||
3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level.
|
||||
|
||||
@@ -3,7 +3,7 @@ name: library-logger-info
|
||||
group: api
|
||||
category: facade
|
||||
update-time: 20260613
|
||||
description: Emit an info-level record through a LibraryLogger facade using the informational severity shortcut.
|
||||
description: Emit an info-level record through a LibraryLogger facade by delegating to the wrapped logger's info shortcut.
|
||||
key-word:
|
||||
- library
|
||||
- facade
|
||||
@@ -39,10 +39,12 @@ pub fn[S : Sink] LibraryLogger::info(
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper delegates to `log(Level::Info, ...)` on the wrapped logger.
|
||||
- This helper delegates to `info(...)` on the wrapped logger, which in turn uses `log(Level::Info, ...)`.
|
||||
- `Info` is the default minimum logger threshold unless changed explicitly.
|
||||
- Per-call target override is not exposed here; use `log(...)` if needed.
|
||||
- Any existing sink wrappers inside the logger pipeline still participate normally in the write path.
|
||||
- The library facade keeps the same write semantics while exposing a smaller public surface.
|
||||
- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first.
|
||||
|
||||
### How to Use
|
||||
|
||||
@@ -66,6 +68,8 @@ logger.info("request completed", fields=[field("status", "200")])
|
||||
|
||||
In this example, the event remains concise while still carrying useful fields.
|
||||
|
||||
And any shared context already carried by the facade still participates through the wrapped logger pipeline.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
@@ -73,8 +77,12 @@ e.g.:
|
||||
|
||||
- If the event needs an explicit alternate target, use `log(...)` instead of this shortcut.
|
||||
|
||||
- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. This is the common convenience method for normal library-facing events.
|
||||
|
||||
2. Because `Info` is often the default threshold, this helper is a natural baseline for facade examples.
|
||||
|
||||
3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level.
|
||||
|
||||
@@ -3,7 +3,7 @@ name: library-logger-is-enabled
|
||||
group: api
|
||||
category: facade
|
||||
update-time: 20260613
|
||||
description: Check whether a LibraryLogger facade would accept a record at a given level.
|
||||
description: Check whether a LibraryLogger facade passes the wrapped logger's min-level gate for a given severity.
|
||||
key-word:
|
||||
- library
|
||||
- facade
|
||||
@@ -35,8 +35,9 @@ pub fn[S] LibraryLogger::is_enabled(self : LibraryLogger[S], level : Level) -> B
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This method delegates directly to the wrapped logger's `is_enabled(...)` behavior.
|
||||
- It only checks logger-level severity gating; it does not evaluate sink filters or patch logic.
|
||||
- The result reflects the current facade value, so derived facades with different thresholds can return different answers.
|
||||
- It only checks logger-level severity gating through `min_level`; it does not evaluate later sink filters, patch logic, or any sink-side buffering/wrapping behavior.
|
||||
- The result reflects the current wrapped logger state, so derived facades with different thresholds can return different answers.
|
||||
- This check does not require unwrapping because it is part of the narrower library-facing surface.
|
||||
- Use it when message construction or field gathering is expensive enough to justify a pre-check.
|
||||
|
||||
### How to Use
|
||||
@@ -65,6 +66,8 @@ if logger.is_enabled(Level::Info) {
|
||||
|
||||
In this example, the check mirrors the same severity gate used by later write calls.
|
||||
|
||||
And a `true` result still means only that the level gate passed, not that the record is guaranteed to survive later sink-side filtering or routing.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
@@ -72,8 +75,12 @@ e.g.:
|
||||
|
||||
- A `true` result does not guarantee final sink output if later filter logic rejects the record.
|
||||
|
||||
- If callers need broader composition helpers rather than just the level gate, they must unwrap first with `to_logger()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. This is a cheap severity check, not a full end-to-end delivery guarantee.
|
||||
|
||||
2. Prefer using it only when precomputing the log payload is meaningfully expensive.
|
||||
|
||||
3. Use `log(...)` or the severity shortcuts directly when no expensive precomputation needs to be avoided.
|
||||
|
||||
@@ -3,7 +3,7 @@ name: library-logger-log
|
||||
group: api
|
||||
category: facade
|
||||
update-time: 20260613
|
||||
description: Emit a record through a LibraryLogger facade with explicit level, message, fields, and optional target override.
|
||||
description: Emit a record through a LibraryLogger facade with explicit level, message, fields, and optional target override by delegating to the wrapped logger.
|
||||
key-word:
|
||||
- library
|
||||
- facade
|
||||
@@ -46,7 +46,9 @@ Detailed rules explaining key parameters and behaviors
|
||||
- This method delegates directly to the wrapped logger's `log(...)` behavior.
|
||||
- The logger checks `is_enabled(level)` before building and writing the record.
|
||||
- If `target` is empty, the facade's stored default target is used.
|
||||
- Any existing sink wrappers already inside the wrapped logger, such as `ContextSink`, `FilterSink`, `PatchSink`, or queued/runtime sink variants, still participate normally in the write path.
|
||||
- The narrower library facade does not change record construction semantics; it only limits the visible API surface.
|
||||
- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first.
|
||||
|
||||
### How to Use
|
||||
|
||||
@@ -77,6 +79,20 @@ fn log_retry(logger : LibraryLogger[ConsoleSink], attempt : Int) -> Unit {
|
||||
|
||||
In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers.
|
||||
|
||||
#### When Need Shared Context Plus Event-specific Fields
|
||||
|
||||
When a facade already carries shared context but one write needs extra detail:
|
||||
```moonbit
|
||||
let logger = base.with_context_fields([field("service", "cache")])
|
||||
logger.log(
|
||||
Level::Info,
|
||||
"entry refreshed",
|
||||
fields=[field("key", "user:42")],
|
||||
)
|
||||
```
|
||||
|
||||
In this example, both the stored shared context and the per-call fields still flow through the wrapped logger pipeline.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
@@ -84,8 +100,12 @@ e.g.:
|
||||
|
||||
- If `target` is empty and the logger default target is also empty, the emitted record simply has no target label.
|
||||
|
||||
- If callers need broader composition helpers after writing, they must unwrap first with `to_logger()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this API when the call site needs full control instead of a fixed-severity helper.
|
||||
|
||||
2. The facade remains synchronous; any buffering behavior only comes from the wrapped sink type.
|
||||
|
||||
3. Use the optional `target` argument when one write should temporarily override the facade's default target without rebuilding or rewrapping it.
|
||||
|
||||
@@ -3,7 +3,7 @@ name: library-logger-warn
|
||||
group: api
|
||||
category: facade
|
||||
update-time: 20260613
|
||||
description: Emit a warn-level record through a LibraryLogger facade using the warning severity shortcut.
|
||||
description: Emit a warn-level record through a LibraryLogger facade by delegating to the wrapped logger's warn shortcut.
|
||||
key-word:
|
||||
- library
|
||||
- facade
|
||||
@@ -39,10 +39,11 @@ pub fn[S : Sink] LibraryLogger::warn(
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper delegates to `log(Level::Warn, ...)` on the wrapped logger.
|
||||
- This helper delegates to `warn(...)` on the wrapped logger, which in turn uses `log(Level::Warn, ...)`.
|
||||
- Warning records are useful for abnormal but non-fatal conditions.
|
||||
- Per-call target override is not exposed here; use `log(...)` when that is required.
|
||||
- All logger wrappers still participate normally in the write path.
|
||||
- All sink-side wrappers still participate normally in the write path.
|
||||
- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first.
|
||||
|
||||
### How to Use
|
||||
|
||||
@@ -66,6 +67,8 @@ logger.warn("retry scheduled", fields=[field("attempt", "3")])
|
||||
|
||||
In this example, the warning remains easy to filter and inspect later.
|
||||
|
||||
And any shared context already carried by the facade still participates through the wrapped logger pipeline.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
@@ -73,8 +76,12 @@ e.g.:
|
||||
|
||||
- If a target override is needed at this call site, use `log(...)` instead of this shortcut.
|
||||
|
||||
- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for degraded or suspicious states that do not stop execution.
|
||||
|
||||
2. Warning logs are often a practical signal threshold for alerting or separate routing.
|
||||
|
||||
3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level.
|
||||
|
||||
Reference in New Issue
Block a user