naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-07-24 17:02:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 document sync library facade write apis

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-13 20:42:12 +08:00
parent 13f0a24336
commit cff282db2f
6 changed files with 415 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/index.md
+5
View File
@@ -212,6 +212,11 @@ BitLogger API navigation.
- [library-logger-child.md](./library-logger-child.md)
- [library-logger-with-context-fields.md](./library-logger-with-context-fields.md)
- [library-logger-bind.md](./library-logger-bind.md)
- [library-logger-is-enabled.md](./library-logger-is-enabled.md)
- [library-logger-log.md](./library-logger-log.md)
- [library-logger-info.md](./library-logger-info.md)
- [library-logger-warn.md](./library-logger-warn.md)
- [library-logger-error.md](./library-logger-error.md)
- [build-application-logger.md](./build-application-logger.md)
- [parse-and-build-application-logger.md](./parse-and-build-application-logger.md)
- [build-library-logger.md](./build-library-logger.md)
docs/api/library-logger-error.md
+80
View File
@@ -0,0 +1,80 @@
---
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.
key-word:
- library
- facade
- error
- public
---
## Library-logger-error
Emit an error-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Error, ...)` on `LibraryLogger[S]`.
### Interface
```moonbit
pub fn[S : Sink] LibraryLogger::error(
self : LibraryLogger[S],
message : String,
fields~ : Array[Field] = [],
) -> Unit {
```
#### input
- `self : LibraryLogger[S]` - Library-facing logger that should emit the error record.
- `message : String` - Error message text.
- `fields : Array[Field]` - Optional structured fields attached to the record.
#### output
- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Error, ...)` on the wrapped logger.
- `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.
### How to Use
Here are some specific examples provided.
#### When Report A Failing Library Operation
When an operation should emit a high-severity failure event:
```moonbit
logger.error("worker execution failed")
```
In this example, the call site clearly communicates failure severity.
#### When Attach Structured Error Context
When an error event should include diagnostic fields:
```moonbit
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.
### Error Case
e.g.:
- If the logger minimum level is above `Error`, the call still returns without writing, though this configuration is unusual.
- If a target override is required, use `log(...)` instead of this severity shortcut.
### Notes
1. Use this helper for high-severity library failures.
2. Emitting an error record is separate from throwing or handling program exceptions.
docs/api/library-logger-info.md
+80
View File
@@ -0,0 +1,80 @@
---
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.
key-word:
- library
- facade
- info
- public
---
## Library-logger-info
Emit an info-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Info, ...)` on `LibraryLogger[S]`.
### Interface
```moonbit
pub fn[S : Sink] LibraryLogger::info(
self : LibraryLogger[S],
message : String,
fields~ : Array[Field] = [],
) -> Unit {
```
#### input
- `self : LibraryLogger[S]` - Library-facing logger that should emit the info record.
- `message : String` - Informational message text.
- `fields : Array[Field]` - Optional structured fields attached to the record.
#### output
- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Info, ...)` on the wrapped logger.
- `Info` is the default minimum logger threshold unless changed explicitly.
- Per-call target override is not exposed here; use `log(...)` if needed.
- The library facade keeps the same write semantics while exposing a smaller public surface.
### How to Use
Here are some specific examples provided.
#### When Emit Normal Library Lifecycle Events
When a package should report standard lifecycle milestones:
```moonbit
logger.info("service started")
```
In this example, the event uses normal informational severity through the narrower facade.
#### When Attach Structured Informational Context
When an info event should include machine-readable metadata:
```moonbit
logger.info("request completed", fields=[field("status", "200")])
```
In this example, the event remains concise while still carrying useful fields.
### Error Case
e.g.:
- If the logger minimum level is above `Info`, the call returns without writing a record.
- If the event needs an explicit alternate target, use `log(...)` instead of this shortcut.
### 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.
docs/api/library-logger-is-enabled.md
+79
View File
@@ -0,0 +1,79 @@
---
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.
key-word:
- library
- facade
- enabled
- public
---
## Library-logger-is-enabled
Check whether a `LibraryLogger[S]` would accept a record at the given level based on its current `min_level`. This is the library-facing counterpart to `Logger::is_enabled(...)` and is useful for gating expensive message preparation.
### Interface
```moonbit
pub fn[S] LibraryLogger::is_enabled(self : LibraryLogger[S], level : Level) -> Bool {
```
#### input
- `self : LibraryLogger[S]` - Library-facing logger whose current minimum level should be checked.
- `level : Level` - Candidate severity to test.
#### output
- `Bool` - `true` when the level is enabled by the facade's current threshold.
### Explanation
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.
- Use it when message construction or field gathering is expensive enough to justify a pre-check.
### How to Use
Here are some specific examples provided.
#### When Avoid Expensive Library Debug Preparation
When debug data should only be built if needed:
```moonbit
if logger.is_enabled(Level::Debug) {
logger.info(build_summary())
}
```
In this example, expensive preparation is skipped unless the current threshold allows that severity.
#### When Inspect Effective Facade Threshold
When package code should branch based on current logger behavior:
```moonbit
if logger.is_enabled(Level::Info) {
logger.info("library path active")
}
```
In this example, the check mirrors the same severity gate used by later write calls.
### Error Case
e.g.:
- If `level` is below the current minimum threshold, the method returns `false`.
- A `true` result does not guarantee final sink output if later filter logic rejects the record.
### 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.
docs/api/library-logger-log.md
+91
View File
@@ -0,0 +1,91 @@
---
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.
key-word:
- library
- facade
- log
- public
---
## Library-logger-log
Emit a record through the library-facing sync logger with an explicit level and message. This is the core write API behind the level-specific `LibraryLogger` convenience methods.
### Interface
```moonbit
pub fn[S : Sink] LibraryLogger::log(
self : LibraryLogger[S],
level : Level,
message : String,
fields~ : Array[Field] = [],
target? : String = "",
) -> Unit {
```
#### input
- `self : LibraryLogger[S]` - Library-facing logger that should emit the record.
- `level : Level` - Severity level for the record.
- `message : String` - Log message text.
- `fields : Array[Field]` - Optional structured fields attached to the record.
- `target : String` - Optional per-call target override.
#### output
- `Unit` - No return value. The record is either skipped by level gating or written to the wrapped sink pipeline.
### Explanation
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.
- The narrower library facade does not change record construction semantics; it only limits the visible API surface.
### How to Use
Here are some specific examples provided.
#### When Need Full Per-call Control Through The Library Facade
When library code should choose level, fields, and target explicitly:
```moonbit
logger.log(
Level::Info,
"worker started",
fields=[field("job", "sync")],
target="service.worker",
)
```
In this example, the call site controls every major record property while keeping the narrower facade type.
#### When Build Higher-level Library Wrappers
When package code defines its own logging helpers:
```moonbit
fn log_retry(logger : LibraryLogger[ConsoleSink], attempt : Int) -> Unit {
logger.log(Level::Warn, "retry scheduled", fields=[field("attempt", attempt.to_string())])
}
```
In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers.
### Error Case
e.g.:
- If `level` is below the current minimum threshold, the method returns without writing a record.
- If `target` is empty and the logger default target is also empty, the emitted record simply has no target label.
### 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.
docs/api/library-logger-warn.md
+80
View File
@@ -0,0 +1,80 @@
---
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.
key-word:
- library
- facade
- warn
- public
---
## Library-logger-warn
Emit a warn-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Warn, ...)` on `LibraryLogger[S]`.
### Interface
```moonbit
pub fn[S : Sink] LibraryLogger::warn(
self : LibraryLogger[S],
message : String,
fields~ : Array[Field] = [],
) -> Unit {
```
#### input
- `self : LibraryLogger[S]` - Library-facing logger that should emit the warning record.
- `message : String` - Warning message text.
- `fields : Array[Field]` - Optional structured fields attached to the record.
#### output
- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Warn, ...)` on the wrapped logger.
- 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.
### How to Use
Here are some specific examples provided.
#### When Signal A Recoverable Library Problem
When an operation degraded but still continued:
```moonbit
logger.warn("cache miss ratio increased")
```
In this example, the event is elevated above normal information without being treated as a hard failure.
#### When Attach Structured Warning Context
When a warning should include machine-readable detail:
```moonbit
logger.warn("retry scheduled", fields=[field("attempt", "3")])
```
In this example, the warning remains easy to filter and inspect later.
### Error Case
e.g.:
- If the logger minimum level is above `Warn`, the call returns without writing a record.
- If a target override is needed at this call site, use `log(...)` instead of this shortcut.
### 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.