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 public config and level aliases

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-13 20:56:46 +08:00
parent 3881ca505a
commit 17c1b95a61
7 changed files with 437 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/async-flush-policy.md
+71
View File
@@ -0,0 +1,71 @@
---
name: async-flush-policy
group: api
category: async
update-time: 20260613
description: Public flush policy alias used by AsyncLoggerConfig and async worker flushing.
key-word:
- async
- flush
- alias
- public
---
## Async-flush-policy
`AsyncFlushPolicy` is the public enum that defines when an async logger should call its flush function. It is a direct alias to the async model enum used by `AsyncLoggerConfig`, worker execution, and async logger state reporting.
### Interface
```moonbit
pub type AsyncFlushPolicy = @utils.AsyncFlushPolicy
```
#### output
- `AsyncFlushPolicy` - Public async flush enum with the variants `Never`, `Batch`, and `Shutdown`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a separate lifecycle wrapper.
- `AsyncFlushPolicy::Never` skips explicit flush calls from the async worker.
- `AsyncFlushPolicy::Batch` calls the configured flush function after each processed batch.
- `AsyncFlushPolicy::Shutdown` calls the configured flush function once after the worker loop exits.
- The current flush policy is also exposed through `AsyncLogger::flush_policy()` and included in `AsyncLoggerState`.
### How to Use
Here are some specific examples provided.
#### When Need Explicit Flush After Every Processed Batch
When buffered sinks should flush incrementally during worker execution:
```moonbit
let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Batch)
```
In this example, each batch run triggers the provided flush callback.
#### When Need One Final Flush During Shutdown
When sink flushing should be deferred until the worker finishes:
```moonbit
let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Shutdown)
```
In this example, flushing happens when the worker loop exits instead of after each batch.
### Error Case
e.g.:
- If async config text uses unsupported flush policy text, async config parsing raises a failure.
- If a sink never needs explicit flushing, `Batch` or `Shutdown` can add unnecessary work without changing output.
### Notes
1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.
2. `AsyncFlushPolicy::Never` is the default in `AsyncLoggerConfig::new(...)`.
docs/api/async-overflow-policy.md
+71
View File
@@ -0,0 +1,71 @@
---
name: async-overflow-policy
group: api
category: async
update-time: 20260613
description: Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.
key-word:
- async
- overflow
- alias
- public
---
## Async-overflow-policy
`AsyncOverflowPolicy` is the public enum that controls what an `AsyncLogger` should do when its queue cannot accept a record immediately. It is a direct alias to the async model enum used by `AsyncLoggerConfig` and the runtime queue selection logic.
### Interface
```moonbit
pub type AsyncOverflowPolicy = @utils.AsyncOverflowPolicy
```
#### output
- `AsyncOverflowPolicy` - Public async queue overflow enum with the variants `Blocking`, `DropOldest`, and `DropNewest`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a separate runtime adapter.
- `AsyncOverflowPolicy::Blocking` waits for queue space when a non-blocking enqueue does not succeed.
- `AsyncOverflowPolicy::DropOldest` lets the underlying async queue discard older pending records when capacity is limited.
- `AsyncOverflowPolicy::DropNewest` discards the incoming record instead of blocking.
- The same enum is used by `AsyncLoggerConfig::new(...)`, async config parsing, and the queue-kind mapping inside `AsyncLogger`.
### How to Use
Here are some specific examples provided.
#### When Need Backpressure Instead Of Silent Dropping
When producers should wait for queue space:
```moonbit
let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::Blocking)
```
In this example, logging pressure can slow producers instead of dropping data immediately.
#### When Need Bounded Async Logging With Drop Behavior
When async logging should keep moving under load without blocking callers:
```moonbit
let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::DropNewest)
```
In this example, the incoming record is dropped if the queue cannot accept it.
### Error Case
e.g.:
- If async config text uses unsupported overflow text, async config parsing raises a failure.
- Under drop policies, sustained overload increases `dropped_count()` instead of guaranteeing delivery.
### Notes
1. This policy applies to `bitlogger_async`, not synchronous `QueuedSink`.
2. Choose `Blocking` only when producer-side waiting is acceptable for the caller.
docs/api/config-error.md
+77
View File
@@ -0,0 +1,77 @@
---
name: config-error
group: api
category: config
update-time: 20260613
description: Public config parsing error alias used by synchronous config-loading helpers.
key-word:
- config
- error
- alias
- public
---
## Config-error
`ConfigError` is the public error type raised by synchronous config parsing helpers. It is a direct alias to the internal config error definition and currently exposes a single structured error case for invalid input.
### Interface
```moonbit
pub type ConfigError = @utils.ConfigError
```
#### output
- `ConfigError` - Public config parsing error type with the case `InvalidConfig(String)`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a separate public wrapper.
- The current public error case is `ConfigError::InvalidConfig(message)`.
- The alias is used by parsing helpers such as `parse_logger_config_text(...)` and by lower-level config parsing routines beneath it.
- Error messages describe concrete schema problems such as invalid JSON, wrong value types, unsupported enum text, or missing required values for a chosen sink kind.
### How to Use
Here are some specific examples provided.
#### When Need To Catch Config Parse Failures
When raw config text should be validated before boot:
```moonbit
let config = parse_logger_config_text(raw) catch {
err if err is ConfigError => {
println(err.to_string())
return
}
}
```
In this example, the caller keeps config validation failures separate from normal runtime work.
#### When Need To Surface A Clear Parse Message
When tooling should report why config input was rejected:
```moonbit
ignore(parse_logger_config_text("{bad json}")) catch {
err => println(err.to_string())
}
```
In this example, the error carries a concrete message instead of failing silently.
### Error Case
e.g.:
- Invalid JSON input raises `ConfigError::InvalidConfig(...)`.
- Wrong field types, unsupported level text, unsupported sink kinds, or an empty `path` for a file sink also raise `ConfigError::InvalidConfig(...)`.
### Notes
1. This alias currently belongs to the synchronous config-loading path in `bitlogger`.
2. Async config parsers in `bitlogger_async` currently raise the generic failure surface used by that package instead of `ConfigError`.
docs/api/index.md
+6
View File
@@ -77,6 +77,7 @@ BitLogger API navigation.
## Record and level
- [record-new.md](./record-new.md)
- [level.md](./level.md)
- [level-priority.md](./level-priority.md)
- [level-label.md](./level-label.md)
- [level-enabled.md](./level-enabled.md)
@@ -93,6 +94,7 @@ BitLogger API navigation.
- [split-by-level.md](./split-by-level.md)
- [buffered-sink.md](./buffered-sink.md)
- [queued-sink.md](./queued-sink.md)
- [queue-overflow-policy.md](./queue-overflow-policy.md)
- [filter-sink.md](./filter-sink.md)
- [patch-sink.md](./patch-sink.md)
- [file-sink.md](./file-sink.md)
@@ -130,6 +132,8 @@ BitLogger API navigation.
## Config build flow
- [config-error.md](./config-error.md)
- [sink-kind.md](./sink-kind.md)
- [queue-config.md](./queue-config.md)
- [queue-config-to-json.md](./queue-config-to-json.md)
- [stringify-queue-config.md](./stringify-queue-config.md)
@@ -190,6 +194,8 @@ BitLogger API navigation.
## Async runtime and config
- [async-overflow-policy.md](./async-overflow-policy.md)
- [async-flush-policy.md](./async-flush-policy.md)
- [async-runtime-mode.md](./async-runtime-mode.md)
- [async-runtime-mode-label.md](./async-runtime-mode-label.md)
- [async-runtime-supports-background-worker.md](./async-runtime-supports-background-worker.md)
docs/api/level.md
+70
View File
@@ -0,0 +1,70 @@
---
name: level
group: api
category: level
update-time: 20260613
description: Public level enum alias shared by records, filters, and logger thresholds.
key-word:
- level
- alias
- severity
- public
---
## Level
`Level` is the public severity enum used across records, filters, and logger threshold checks. It is a direct alias to the core level type, so the same five built-in variants are shared everywhere the public API accepts or returns a level.
### Interface
```moonbit
pub type Level = @core.Level
```
#### output
- `Level` - Public severity enum with the variants `Trace`, `Debug`, `Info`, `Warn`, and `Error`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a wrapper or a separate enum.
- The built-in variants are `Level::Trace`, `Level::Debug`, `Level::Info`, `Level::Warn`, and `Level::Error`.
- `Level` is used by `Record::new(...)`, logger threshold APIs, predicate helpers, and config-driven builders.
- Ordering and display behavior come from the same underlying type, so helpers such as `priority()`, `label()`, and `enabled(...)` work on this alias unchanged.
### How to Use
Here are some specific examples provided.
#### When Need A Severity For New Records
When a record should be created with a concrete severity:
```moonbit
let rec = Record::new(Level::Warn, "disk almost full")
```
In this example, the record uses the public `Level` alias directly.
#### When Need A Threshold For Logger Filtering
When a logger should only accept records at or above one severity:
```moonbit
let logger = Logger::new(console_sink()).with_min_level(Level::Info)
```
In this example, the same public level enum is reused as the threshold value.
### Error Case
e.g.:
- `Level` itself does not have a runtime failure mode.
- If external config text names an unsupported level string, parsing fails through `ConfigError` instead of producing a fallback level.
### Notes
1. Use `label()` for display text and `priority()` or `enabled(...)` for threshold logic.
2. This alias keeps sync APIs, async APIs, and config builders on the same severity vocabulary.
docs/api/queue-overflow-policy.md
+70
View File
@@ -0,0 +1,70 @@
---
name: queue-overflow-policy
group: api
category: sink
update-time: 20260613
description: Public overflow policy alias used by synchronous queued sinks and queue config.
key-word:
- queue
- overflow
- alias
- public
---
## Queue-overflow-policy
`QueueOverflowPolicy` is the public enum that defines what a synchronous queue should do when it reaches `max_pending`. It is a direct alias to the queue model enum used by both `QueuedSink` and `QueueConfig`.
### Interface
```moonbit
pub type QueueOverflowPolicy = @utils.QueueOverflowPolicy
```
#### output
- `QueueOverflowPolicy` - Public synchronous queue overflow enum with the variants `DropNewest` and `DropOldest`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a separate policy wrapper.
- `QueueOverflowPolicy::DropNewest` keeps the existing queued records and drops the incoming one when the queue is full.
- `QueueOverflowPolicy::DropOldest` removes one pending record and enqueues the new record instead.
- The same enum is used by code-side queue composition through `queued_sink(...)` and config-driven queue composition through `QueueConfig::new(...)`.
### How to Use
Here are some specific examples provided.
#### When Need A Bounded Queue That Prefers Older Pending Records
When the oldest pending records should be preserved and new bursts can be dropped:
```moonbit
let sink = queued_sink(console_sink(), max_pending=32, overflow=QueueOverflowPolicy::DropNewest)
```
In this example, new records are discarded once the queue is full.
#### When Need To Prefer Fresh Records Over Old Pending Work
When backlog should make room for newer records:
```moonbit
let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
```
In this example, the oldest pending record is removed when the queue overflows.
### Error Case
e.g.:
- If a queue is unbounded or never reaches capacity, the overflow policy has no effect.
- If parsed JSON uses unsupported overflow text, config parsing raises `ConfigError`.
### Notes
1. This policy belongs to synchronous queue wrappers, not `bitlogger_async`.
2. Use `AsyncOverflowPolicy` for the async logger queue behavior.
docs/api/sink-kind.md
+72
View File
@@ -0,0 +1,72 @@
---
name: sink-kind
group: api
category: config
update-time: 20260613
description: Public sink kind enum alias used by SinkConfig and config parsing.
key-word:
- sink
- config
- alias
- public
---
## Sink-kind
`SinkKind` is the public enum that selects which built-in sink shape a `SinkConfig` should build. It is a direct alias to the internal config enum, so config builders, JSON parsers, and sink serialization helpers all use the same small set of variants.
### Interface
```moonbit
pub type SinkKind = @utils.SinkKind
```
#### output
- `SinkKind` - Public sink selection enum with the variants `Console`, `JsonConsole`, `TextConsole`, and `File`.
### Explanation
Detailed rules explaining key parameters and behaviors
- This is a type alias, not a wrapper or a new runtime sink implementation.
- `SinkKind::Console` selects the basic text console sink.
- `SinkKind::JsonConsole` selects JSON line output.
- `SinkKind::TextConsole` selects text console output driven by `TextFormatterConfig`.
- `SinkKind::File` selects file-backed output and requires a non-empty `path` during config parsing.
### How to Use
Here are some specific examples provided.
#### When Need To Build A File Sink Through Config
When logger construction should be described entirely as config data:
```moonbit
let sink = SinkConfig::new(kind=SinkKind::File, path="app.log")
let config = LoggerConfig::new(sink=sink)
```
In this example, the selected enum variant controls which built-in sink builder will be used.
#### When Need Formatter-driven Console Output
When the config should request text console formatting instead of the default console sink:
```moonbit
let sink = SinkConfig::new(kind=SinkKind::TextConsole)
```
In this example, the enum value makes the config intent explicit.
### Error Case
e.g.:
- Unsupported sink kind text in parsed JSON raises `ConfigError`.
- `SinkKind::File` without a non-empty `path` is rejected during config parsing.
### Notes
1. This enum is for config-driven sink selection, not for direct handwritten sink composition.
2. Use concrete constructors such as `console_sink()` or `file_sink(...)` when building sinks in code instead of through `SinkConfig`.