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

📝 Add async logger write API docs

Browse Source
This commit is contained in:
Nanaloveyuki
2026-05-12 14:04:44 +08:00
parent dad55a241f
commit d7f93e9f9c
7 changed files with 583 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/async-logger-debug.md
+83
View File
@@ -0,0 +1,83 @@
---
name: async-logger-debug
group: api
category: async
update-time: 20260512
description: Enqueue a debug-level record through the async logger using the built-in severity shortcut.
key-word:
- async
- logger
- debug
- public
---
## Async-logger-debug
Enqueue a debug-level record through the async logger. This is the convenience wrapper for `log(Level::Debug, ...)`.
### Interface
```moonbit
pub async fn[S] AsyncLogger::debug(
self : AsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the debug record.
- `message : String` - Debug message text.
- `fields : Array[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::Debug, ...)`.
- The record is still subject to min-level gating, patching, filtering, and overflow policy.
- Debug records are useful for development and targeted diagnostics.
- Use this helper when a named debug call is clearer than a raw `log(...)` call.
### How to Use
Here are some specific examples provided.
#### When Need Async Development Diagnostics
When intermediate async flow details should be visible during debugging:
```moonbit
await logger.debug("loaded worker config")
```
In this example, the call site communicates its intended diagnostic level directly.
#### When Attach Structured Debug Context
When a debug event should include extra fields:
```moonbit
await logger.debug(
"dispatch start",
fields=[@bitlogger.field("job_id", "42")],
)
```
In this example, the record carries structured context without needing the generic `log(...)` form.
### Error Case
e.g.:
- If the logger minimum level is above `Debug`, 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. Prefer this helper when the event is semantically debug-level.
2. Use `log(...)` when the level must be chosen dynamically.
docs/api/async-logger-error.md
+83
View File
@@ -0,0 +1,83 @@
---
name: async-logger-error
group: api
category: async
update-time: 20260512
description: Enqueue an error-level record through the async logger using the highest built-in severity shortcut.
key-word:
- async
- logger
- error
- public
---
## Async-logger-error
Enqueue an error-level record through the async logger. This is the convenience wrapper for `log(Level::Error, ...)`.
### Interface
```moonbit
pub async fn[S] AsyncLogger::error(
self : AsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the error record.
- `message : String` - Error message text.
- `fields : Array[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, ...)`.
- The record is still subject to patching, filtering, and overflow policy.
- Error records represent the highest built-in severity in this logger 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
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.
### 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/async-logger-info.md
+83
View File
@@ -0,0 +1,83 @@
---
name: async-logger-info
group: api
category: async
update-time: 20260512
description: Enqueue an info-level record through the async logger using the most common built-in severity shortcut.
key-word:
- async
- logger
- info
- public
---
## Async-logger-info
Enqueue an info-level record through the async logger. This is the convenience wrapper for `log(Level::Info, ...)`.
### Interface
```moonbit
pub async fn[S] AsyncLogger::info(
self : AsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the info record.
- `message : String` - Info message text.
- `fields : Array[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, ...)`.
- 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 Events
When async code should report routine progress or lifecycle events:
```moonbit
await logger.info("worker started")
```
In this example, the event is expressed at the most common operational logging level.
#### 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 application events.
2. Use `log(...)` when the call site needs a dynamic level or target override.
docs/api/async-logger-log.md
+89
View File
@@ -0,0 +1,89 @@
---
name: async-logger-log
group: api
category: async
update-time: 20260512
description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override.
key-word:
- async
- logger
- log
- public
---
## Async-logger-log
Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods.
### Interface
```moonbit
pub async fn[S] AsyncLogger::log(
self : AsyncLogger[S],
level : @bitlogger.Level,
message : String,
fields~ : Array[@bitlogger.Field] = [],
target? : String = "",
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the record.
- `level : Level` - Severity level for the record.
- `message : String` - Log message text.
- `fields : Array[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
- The logger checks `is_enabled(level)` before building a record.
- Context fields, patch logic, and filter logic are applied before enqueue.
- If timestamping is enabled, `@env.now()` is captured before the record enters the queue.
- Overflow behavior depends on the configured `AsyncOverflowPolicy`.
### How to Use
Here are some specific examples provided.
#### When Need A Fully Explicit Async Log Call
When 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, all per-record inputs are supplied explicitly.
#### When Build Higher-level Async Logging Helpers
When application code wants a custom wrapper around the base API:
```moonbit
await logger.log(@bitlogger.Level::Warn, "slow request")
```
In this example, `log(...)` acts as the common primitive under custom wrappers or convenience methods.
### 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()`, and the other shortcuts when only the level differs.
docs/api/async-logger-run.md
+79
View File
@@ -0,0 +1,79 @@
---
name: async-logger-run
group: api
category: async
update-time: 20260512
description: Start the async logger worker loop so queued records are drained to the underlying sink.
key-word:
- async
- logger
- worker
- public
---
## Async-logger-run
Start the async logger worker loop. This is the core runtime API that drains queued records to the underlying sink and updates worker lifecycle state.
### Interface
```moonbit
pub async fn[S : @bitlogger.Sink] AsyncLogger::run(self : AsyncLogger[S]) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - 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
- `run()` sets `is_running` to `true` while the worker loop is active.
- It clears previous failure state before worker execution begins.
- On failure, the logger records `has_failed=true` and stores the error text in `last_error`.
- The worker exits when the queue is closed or when a failure aborts processing.
### How to Use
Here are some specific examples provided.
#### When Need Background Queue Drain
When async logging should be processed by a worker task:
```moonbit
let logger = async_logger(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 logger actually deliver queued records.
#### When Need Explicit Worker Lifetime Control
When worker execution should be started under application control:
```moonbit
group.spawn_bg(() => logger.run())
```
In this example, the application decides when the worker begins instead of hiding that lifecycle step.
### Error Case
e.g.:
- If the worker loop fails, `has_failed()` becomes `true` and `last_error()` stores the error text.
- If `run()` is never started, accepted records may remain queued and not reach the sink.
### Notes
1. `async_logger(...)` only constructs the logger; `run()` is what activates queue draining.
2. Pair this API with `shutdown()` for a complete worker lifecycle.
docs/api/async-logger-trace.md
+83
View File
@@ -0,0 +1,83 @@
---
name: async-logger-trace
group: api
category: async
update-time: 20260512
description: Enqueue a trace-level record through the async logger using the lowest built-in severity shortcut.
key-word:
- async
- logger
- trace
- public
---
## Async-logger-trace
Enqueue a trace-level record through the async logger. This is the convenience wrapper for `log(Level::Trace, ...)`.
### Interface
```moonbit
pub async fn[S] AsyncLogger::trace(
self : AsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the trace record.
- `message : String` - Trace message text.
- `fields : Array[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::Trace, ...)`.
- The record is still subject to min-level gating, patching, filtering, and overflow policy.
- Trace records are often skipped in production because they are the lowest built-in severity.
- Use this helper when explicit trace intent is clearer than a raw `log(...)` call.
### How to Use
Here are some specific examples provided.
#### When Need Fine-grained Async Diagnostics
When low-level execution flow should be observable during debugging:
```moonbit
await logger.trace("entered reconciliation step")
```
In this example, the call site makes trace intent explicit.
#### When Attach Structured Trace Data
When a trace event should carry extra fields:
```moonbit
await logger.trace(
"cache probe",
fields=[@bitlogger.field("key", "user:42")],
)
```
In this example, the record stays lightweight while still carrying structured detail.
### Error Case
e.g.:
- If the logger minimum level is above `Trace`, 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. Prefer this helper when trace intent is more readable than `log(Level::Trace, ...)`.
2. Trace-level async logging can increase queue pressure quickly under verbose workloads.
docs/api/async-logger-warn.md
+83
View File
@@ -0,0 +1,83 @@
---
name: async-logger-warn
group: api
category: async
update-time: 20260512
description: Enqueue a warning-level record through the async logger using the built-in severity shortcut.
key-word:
- async
- logger
- warn
- public
---
## Async-logger-warn
Enqueue a warning-level record through the async logger. This is the convenience wrapper for `log(Level::Warn, ...)`.
### Interface
```moonbit
pub async fn[S] AsyncLogger::warn(
self : AsyncLogger[S],
message : String,
fields~ : Array[@bitlogger.Field] = [],
) -> Unit {}
```
#### input
- `self : AsyncLogger[S]` - Async logger that should receive the warning record.
- `message : String` - Warning message text.
- `fields : Array[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, ...)`.
- 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
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", logger.pending_count().to_string())],
)
```
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.