mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-05-30 15:42:25 +00:00
Nanaloveyuki
106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
---
|
|
name: async-logger
|
|
group: api
|
|
category: async
|
|
update-time: 20260512
|
|
description: Create an async logger with bounded queueing, overflow policy, lifecycle helpers, and background run control.
|
|
key-word:
|
|
- async
|
|
- logger
|
|
- queue
|
|
- public
|
|
---
|
|
|
|
## Async-logger
|
|
|
|
Create an `AsyncLogger[S]` on top of a sink and async queue configuration. This API is the main entry for queue-backed async logging, including overflow policy, batching, lifecycle control, and runtime observability.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn[S] async_logger(
|
|
sink : S,
|
|
config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(),
|
|
min_level~ : @bitlogger.Level = @bitlogger.Level::Info,
|
|
target~ : String = "",
|
|
flush~ : (S) -> Int = fn(_) { 0 },
|
|
) -> AsyncLogger[S] {}
|
|
```
|
|
|
|
#### input
|
|
|
|
- `sink : S` - Underlying sink used after queue drain.
|
|
- `config : AsyncLoggerConfig` - Queue size, overflow behavior, batching, linger, and flush policy.
|
|
- `min_level : Level` - Level gate applied before enqueue.
|
|
- `target : String` - Default target for emitted records.
|
|
- `flush : (S) -> Int` - Flush callback used by batch/shutdown flush policies.
|
|
|
|
#### output
|
|
|
|
- `AsyncLogger[S]` - A queue-backed async logger with lifecycle and state helpers.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- `async_logger(...)` only builds the logger. Actual background draining is started by `run()`.
|
|
- In non-native targets, the implementation uses compatibility behavior while keeping the same public surface.
|
|
- `flush` is used only when batch or shutdown policy wants explicit flushing.
|
|
- Queue overflow behavior depends on `AsyncOverflowPolicy`.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need Background Queue Drain
|
|
|
|
When your sink should not be written directly on the caller path:
|
|
```moonbit
|
|
let logger = async_logger(callback_sink(fn(rec) { println(rec.message) }))
|
|
@async.with_task_group(group => {
|
|
group.spawn_bg(() => logger.run())
|
|
logger.info("hello")
|
|
logger.shutdown()
|
|
})
|
|
```
|
|
|
|
In this example, the worker drains queued records in the background and `shutdown()` waits for completion.
|
|
|
|
And the logging call path stays queue-oriented rather than direct-sink oriented.
|
|
|
|
#### When Need Configurable Overflow And Flush Behavior
|
|
|
|
When queue semantics matter for service durability and load:
|
|
```moonbit
|
|
let logger = async_logger(
|
|
console_sink(),
|
|
config=AsyncLoggerConfig::new(
|
|
max_pending=128,
|
|
overflow=AsyncOverflowPolicy::DropOldest,
|
|
max_batch=8,
|
|
flush=AsyncFlushPolicy::Batch,
|
|
),
|
|
)
|
|
```
|
|
|
|
In this example, queue pressure and flush timing are both explicit.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If the logger is closed, further enqueue attempts stop being normal active logging operations.
|
|
|
|
- If queue drain fails internally, runtime state can reflect that through `has_failed()` and `last_error()`.
|
|
|
|
### Notes
|
|
|
|
Notes are here.
|
|
|
|
1. `async_logger(...)` is the async counterpart to `Logger::new(...)`.
|
|
|
|
2. Use `state()`, `pending_count()`, and `dropped_count()` for runtime diagnostics.
|
|
|
|
3. Prefer `shutdown()` over raw `close()` in normal graceful shutdown paths.
|
|
|
|
4. On cross-target code paths, pair this API with `async_runtime_mode()` or `async_runtime_state()` when behavior differences matter.
|