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

📝 document async library facade write apis

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-13 20:45:41 +08:00
parent cff282db2f
commit 00e06c302f
8 changed files with 584 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/index.md
+7
View File
@@ -229,6 +229,13 @@ BitLogger API navigation.
- [library-async-logger-child.md](./library-async-logger-child.md)
- [library-async-logger-with-context-fields.md](./library-async-logger-with-context-fields.md)
- [library-async-logger-bind.md](./library-async-logger-bind.md)
- [library-async-logger-is-enabled.md](./library-async-logger-is-enabled.md)
- [library-async-logger-log.md](./library-async-logger-log.md)
- [library-async-logger-info.md](./library-async-logger-info.md)
- [library-async-logger-warn.md](./library-async-logger-warn.md)
- [library-async-logger-error.md](./library-async-logger-error.md)
- [library-async-logger-run.md](./library-async-logger-run.md)
- [library-async-logger-shutdown.md](./library-async-logger-shutdown.md)
- [build-application-async-logger.md](./build-application-async-logger.md)
- [build-application-text-async-logger.md](./build-application-text-async-logger.md)
- [parse-and-build-application-async-logger.md](./parse-and-build-application-async-logger.md)
docs/api/library-async-logger-error.md
+83
View File
@@ -0,0 +1,83 @@
---
name: library-async-logger-error
group: api
category: facade
update-time: 20260613
description: Enqueue an error-level record through a LibraryAsyncLogger facade using the highest built-in severity shortcut.
key-word:
- async
- library
- error
- public
---
## Library-async-logger-error
Enqueue an error-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Error, ...)` on `LibraryAsyncLogger[S]`.
### Interface
```moonbit
pub async fn[S] LibraryAsyncLogger::error(
self : LibraryAsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the error record.
- `message : String` - Error message text.
- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
#### output
- `Unit` - No return value. The record is handled according to logger state and policy.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Error, ...)` on the wrapped async logger.
- The record is still subject to patching, filtering, and overflow policy.
- Error records represent the highest built-in severity in this async facade API.
- Use this helper when a named error call is clearer than a raw `log(...)` call.
### How to Use
Here are some specific examples provided.
#### When Need Async Failure Reporting In A Library Boundary
When an operation should emit a high-severity failure event:
```moonbit
await logger.error("worker execution failed")
```
In this example, failure intent is explicit at the call site.
#### When Attach Structured Error Context
When an error event should include diagnostic fields:
```moonbit
await logger.error(
"dispatch failed",
fields=[@bitlogger.field("job_id", "42")],
)
```
In this example, the error record carries structured context without falling back to the generic `log(...)` form.
### Error Case
e.g.:
- If the logger is closed or overflow policy prevents acceptance, even an error-level record may not become a normal queued record.
- If callers need to inspect worker failure rather than emit an error record, `has_failed()` and `last_error()` are the relevant APIs on the full async logger.
### Notes
1. Use this helper for high-severity async application failures.
2. Emitting an error record is separate from the logger worker itself entering failure state.
docs/api/library-async-logger-info.md
+83
View File
@@ -0,0 +1,83 @@
---
name: library-async-logger-info
group: api
category: facade
update-time: 20260613
description: Enqueue an info-level record through a LibraryAsyncLogger facade using the informational severity shortcut.
key-word:
- async
- library
- info
- public
---
## Library-async-logger-info
Enqueue an info-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Info, ...)` on `LibraryAsyncLogger[S]`.
### Interface
```moonbit
pub async fn[S] LibraryAsyncLogger::info(
self : LibraryAsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the info record.
- `message : String` - Info message text.
- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
#### output
- `Unit` - No return value. The record is handled according to logger state and policy.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Info, ...)` on the wrapped async logger.
- The record is still subject to min-level gating, patching, filtering, and overflow policy.
- `Info` is often the default operational logging level for async application events.
- Use this helper when explicit info intent is clearer than a raw `log(...)` call.
### How to Use
Here are some specific examples provided.
#### When Need Normal Operational Async Library Events
When async package code should report routine progress or lifecycle events:
```moonbit
await logger.info("worker started")
```
In this example, the event is expressed at the common operational logging level through the narrower facade.
#### When Add Structured Operational Metadata
When an info event should include stable structured detail:
```moonbit
await logger.info(
"job queued",
fields=[@bitlogger.field("queue", "sync")],
)
```
In this example, the record remains concise while still carrying useful metadata.
### Error Case
e.g.:
- If the logger minimum level is above `Info`, the record is skipped before enqueue.
- If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record.
### Notes
1. This is often the most common convenience method for normal async library events.
2. Use `log(...)` when the call site needs a dynamic level or target override.
docs/api/library-async-logger-is-enabled.md
+82
View File
@@ -0,0 +1,82 @@
---
name: library-async-logger-is-enabled
group: api
category: facade
update-time: 20260613
description: Check whether a LibraryAsyncLogger facade would accept a record at a given level.
key-word:
- async
- library
- enabled
- public
---
## Library-async-logger-is-enabled
Check whether a `LibraryAsyncLogger[S]` would accept a record at the given level based on its current `min_level`. This is the library-facing counterpart to `AsyncLogger::is_enabled(...)` and is useful for gating expensive async message preparation.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::is_enabled(
self : LibraryAsyncLogger[S],
level : @bitlogger.Level,
) -> Bool {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger whose current minimum level should be checked.
- `level : @bitlogger.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 async logger's `is_enabled(...)` behavior.
- It only checks logger-level severity gating; it does not evaluate later filter or overflow behavior.
- 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 Async Debug Preparation
When debug data should only be built if needed:
```moonbit
if logger.is_enabled(@bitlogger.Level::Info) {
await logger.info(build_summary())
}
```
In this example, expensive preparation is skipped unless the current threshold allows that severity.
#### When Inspect Effective Async Facade Threshold
When package code should branch based on current logger behavior:
```moonbit
if logger.is_enabled(@bitlogger.Level::Warn) {
await logger.warn("slow path active")
}
```
In this example, the check mirrors the same severity gate used by later async 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 delivery if later queue or filter behavior 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 async log payload is meaningfully expensive.
docs/api/library-async-logger-log.md
+89
View File
@@ -0,0 +1,89 @@
---
name: library-async-logger-log
group: api
category: facade
update-time: 20260613
description: Enqueue a record through a LibraryAsyncLogger facade with explicit level, message, fields, and optional target override.
key-word:
- async
- library
- log
- public
---
## Library-async-logger-log
Enqueue a record through the library-facing async logger with an explicit level and message. This is the core write API behind the level-specific `LibraryAsyncLogger` convenience methods.
### Interface
```moonbit
pub async fn[S] LibraryAsyncLogger::log(
self : LibraryAsyncLogger[S],
level : @bitlogger.Level,
message : String,
fields~ : Array[@bitlogger.Field] = [],
target? : String = "",
) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the record.
- `level : @bitlogger.Level` - Severity level for the record.
- `message : String` - Log message text.
- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
- `target : String` - Optional per-call target override.
#### output
- `Unit` - No return value. The record is either skipped, enqueued, or dropped according to logger state and policy.
### Explanation
Detailed rules explaining key parameters and behaviors
- This method delegates directly to the wrapped async logger's `log(...)` behavior.
- The logger checks `is_enabled(level)` before building a record.
- Context fields, patch logic, and filter logic are applied before enqueue.
- The narrower library facade does not change enqueue 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 Async Facade
When library code should choose level, fields, and target per event:
```moonbit
await logger.log(
@bitlogger.Level::Info,
"worker started",
fields=[@bitlogger.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 Async Library Wrappers
When package code defines its own logging helpers:
```moonbit
await logger.log(@bitlogger.Level::Warn, "slow request")
```
In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers.
### Error Case
e.g.:
- If the level is below the current minimum threshold, the record is skipped before queue insertion.
- If the logger is closed or overflow policy rejects the record, enqueue may not proceed as a normal accepted write.
### Notes
1. Use this API when the call site needs full control instead of a fixed severity helper.
2. Prefer `info()`, `warn()`, `error()`, and the other shortcuts when only the level differs.
docs/api/library-async-logger-run.md
+79
View File
@@ -0,0 +1,79 @@
---
name: library-async-logger-run
group: api
category: facade
update-time: 20260613
description: Start the LibraryAsyncLogger worker loop so queued records are drained to the underlying sink.
key-word:
- async
- library
- worker
- public
---
## Library-async-logger-run
Start the library-facing async logger worker loop. This is the core runtime API that drains queued records to the underlying sink while preserving the narrower facade boundary.
### Interface
```moonbit
pub async fn[S : @bitlogger.Sink] LibraryAsyncLogger::run(self : LibraryAsyncLogger[S]) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger whose queue should be drained by the worker loop.
#### output
- `Unit` - No return value. The method runs until the queue is closed or a worker failure occurs.
### Explanation
Detailed rules explaining key parameters and behaviors
- This method delegates directly to the wrapped async logger's `run()` behavior.
- It starts the worker loop that makes accepted queued records reach the underlying sink.
- Failure and lifecycle state are still tracked by the wrapped async logger.
- The narrower library facade does not hide the need to explicitly activate queue draining.
### How to Use
Here are some specific examples provided.
#### When Need Background Queue Drain Through The Facade
When library async logging should be processed by a worker task:
```moonbit
let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
@async.with_task_group(group => {
group.spawn_bg(() => logger.run())
logger.info("started")
logger.shutdown()
})
```
In this example, `run()` is the worker loop that makes the async facade actually deliver queued records.
#### When Need Explicit Worker Lifetime Control
When worker execution should be started under caller control:
```moonbit
group.spawn_bg(() => logger.run())
```
In this example, the caller decides when the worker begins instead of hiding that lifecycle step.
### Error Case
e.g.:
- If the worker loop fails, the wrapped async logger records failure state.
- If `run()` is never started, accepted records may remain queued and not reach the sink.
### Notes
1. `LibraryAsyncLogger::new(...)` only constructs the facade; `run()` is what activates queue draining.
2. Pair this API with `shutdown()` for a complete worker lifecycle.
docs/api/library-async-logger-shutdown.md
+78
View File
@@ -0,0 +1,78 @@
---
name: library-async-logger-shutdown
group: api
category: facade
update-time: 20260613
description: Gracefully stop a LibraryAsyncLogger by draining or clearing queued work, then waiting for the worker to finish.
key-word:
- async
- library
- lifecycle
- public
---
## Library-async-logger-shutdown
Gracefully stop a library-facing async logger. This is the high-level shutdown API for `LibraryAsyncLogger[S]` because it coordinates drain behavior, closure, and worker completion while preserving the narrower facade surface.
### Interface
```moonbit
pub async fn[S] LibraryAsyncLogger::shutdown(
self : LibraryAsyncLogger[S],
clear? : Bool = false,
) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should be shut down.
- `clear : Bool` - Whether pending records should be abandoned immediately instead of waiting for idle first.
#### output
- `Unit` - No return value. The method completes after shutdown coordination finishes.
### Explanation
Detailed rules explaining key parameters and behaviors
- This method delegates directly to the wrapped async logger's `shutdown(...)` behavior.
- `clear=false` first waits for idle, then closes the logger.
- `clear=true` immediately closes and abandons pending records.
- The method waits until the worker is no longer running before returning.
### How to Use
Here are some specific examples provided.
#### When Need Graceful Async Library Shutdown
When a service should stop logging only after queued records are drained:
```moonbit
await logger.shutdown()
```
In this example, the facade waits for normal drain behavior before final closure.
#### When Need Fast Shutdown Under Pressure
When teardown should prefer speed over preserving backlog:
```moonbit
await logger.shutdown(clear=true)
```
In this example, pending work is abandoned intentionally so shutdown can complete sooner.
### Error Case
e.g.:
- If `clear=true`, pending records are intentionally dropped rather than drained.
- If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
### Notes
1. Prefer this API over low-level closure control in normal library shutdown paths.
2. Choose `clear=true` only when loss of queued records is acceptable.
docs/api/library-async-logger-warn.md
+83
View File
@@ -0,0 +1,83 @@
---
name: library-async-logger-warn
group: api
category: facade
update-time: 20260613
description: Enqueue a warning-level record through a LibraryAsyncLogger facade using the built-in severity shortcut.
key-word:
- async
- library
- warn
- public
---
## Library-async-logger-warn
Enqueue a warning-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Warn, ...)` on `LibraryAsyncLogger[S]`.
### Interface
```moonbit
pub async fn[S] LibraryAsyncLogger::warn(
self : LibraryAsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {
```
#### input
- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the warning record.
- `message : String` - Warning message text.
- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
#### output
- `Unit` - No return value. The record is handled according to logger state and policy.
### Explanation
Detailed rules explaining key parameters and behaviors
- This helper delegates to `log(Level::Warn, ...)` on the wrapped async logger.
- The record is still subject to min-level gating, patching, filtering, and overflow policy.
- Warning records are useful for degraded but non-fatal runtime conditions.
- Use this helper when a named warning call is clearer than a raw `log(...)` call.
### How to Use
Here are some specific examples provided.
#### When Need Async Degradation Signals In Library Code
When the system should report a non-fatal problem:
```moonbit
await logger.warn("retry budget running low")
```
In this example, the event is surfaced at warning severity without using the generic `log(...)` form.
#### When Attach Structured Warning Detail
When a warning event should include context:
```moonbit
await logger.warn(
"queue near capacity",
fields=[@bitlogger.field("pending", "64")],
)
```
In this example, the warning carries structured operational detail.
### Error Case
e.g.:
- If the logger minimum level is above `Warn`, the record is skipped before enqueue.
- If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record.
### Notes
1. Use this helper for notable but non-fatal async runtime conditions.
2. Pair warnings with structured fields when operators need quick context.