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

📝 simplify bilingual readme copy

Browse Source
This commit is contained in:
Nanaloveyuki
2026-05-21 14:22:49 +08:00
parent 6c19708d7b
commit 5c8067d009
2 changed files with 72 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README-en.md
+34 -76
View File
@@ -1,49 +1,22 @@
# BitLogger
BitLogger is a structured logging library written in MoonBit.
BitLogger is a structured logging library for MoonBit projects.
This README focuses on project positioning, core capabilities, and entry points. Detailed API coverage now lives in `docs/api/`.
- [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
- [Chinese README](../README.md)
## Overview
BitLogger is designed to provide composable, configurable, and cross-target logging infrastructure for MoonBit projects.
## Backend Compatibility
Currently verified targets: `native`, `js`, `wasm`, and `wasm-gc`.
`llvm` should still be treated as experimental here: verification did not complete in the current environment, and local reproduction depends on nightly / llvm toolchain conditions, so it is not presented as a stable promise at the same level as `native`.
| Module / capability | Verified targets | `llvm` |
| --- | --- | --- |
| `src` core package | Verified on `native`, `js`, `wasm`, and `wasm-gc` | Experimental; not fully verified in the current environment |
| `file(...)` / `file_sink(...)` | Verified only on `native`; unavailable on non-native targets and `native_files_supported()` returns `false` | Not presented as a verified capability |
| `src-async` | Local verification passed on `native` and `wasm`; other non-native targets still follow the compatibility-implementation wording | Experimental; not fully verified in the current environment |
| portable examples (`console_basic` / `text_formatter` / `style_tags` / `config_build` / `presets`) | Verified on `native` and `wasm-gc` | Not yet verified here |
| `examples/file_rotation` | Verified on `native`; non-native targets print a clear skip message because file sinks are unavailable | Not yet verified here |
| `examples/async_basic` | Verified on `native`; non-native example shipping is still limited by the current `async fn main` entry path | Not yet verified here |
## Key Features
- Structured logging with levels, targets, and key-value fields.
- Composable sinks, filters, patches, fanout, routing, and queue wrappers.
- Config-driven runtime assembly through JSON parse/export helpers and `build_logger(...)` / `build_async_logger(...)`.
- Configurable text formatting with templates, style tags, and color control.
- Native file sink support with basic rotation, reopen helpers, and runtime observability.
- Separate async layer with bounded queueing, worker lifecycle control, runtime state, and cross-target compatibility.
BitLogger gives you consistent levels, targets, structured fields, configurable text output, native file logging, and an async logging layer.
## Quick Start
```moonbit
let logger = build_logger(
with_queue(
text_console(
min_level=Level::Info,
target="demo",
text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
),
max_pending=32,
overflow=QueueOverflowPolicy::DropOldest,
text_console(
min_level=Level::Info,
target="demo",
text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
),
)
@@ -51,54 +24,39 @@ logger.info("starting", fields=[field("port", "8080")])
ignore(logger.flush())
```
Start new synchronous code with `presets + build_logger(...)`: use `console(...)`, `json_console(...)`, `text_console(...)`, or `file(...)` to assemble `LoggerConfig`, optionally extend it with `with_queue(...)` or `with_file_rotation(...)`, then call `build_logger(...)`.
Start with `console(...)`, `json_console(...)`, `text_console(...)`, or `file(...)`, then add `with_queue(...)` or `with_file_rotation(...)` only when needed.
Switch to `Logger::new(...)` when you need direct runtime sink composition such as `fanout`, `split`, `callback`, or custom patch/filter graphs.
Use `Logger::new(...)` when you want to assemble custom sink graphs directly.
For cross-target code, prefer the console, json console, text console, and config-parser paths first. File sinks and file presets remain native-sensitive and should be gated with `native_files_supported()`.
## Support Status
Async entry example:
- Currently verified targets: `native`, `js`, `wasm`, `wasm-gc`
- `llvm` is still treated as experimental in the current release context
- File output is a native capability; check `native_files_supported()` in cross-target code
- `src-async` is available, while `examples/async_basic` is still shipped as a native entry example
```moonbit
let logger = async_logger(console_sink(), target="async.demo")
@async.with_task_group(group => {
group.spawn_bg(() => logger.run())
logger.info("started")
logger.shutdown()
})
```
## Main Features
## Repository Layout
- Structured logs with levels, targets, messages, and fields
- Multiple outputs: console, JSON console, text console, and file
- Custom text formatting with templates, style tags, and color control
- Config-based builders: `build_logger(...)` and `build_async_logger(...)`
- Composition helpers: queue, filter, patch, fanout, split, callback
- Separate async package under `src-async`
- `src/`: core logging package.
- `src-async/`: async logging layer built on `moonbitlang/async`.
- `docs/api/`: one-file-per-interface API documentation.
- `examples/basic/`: breadth example; starts with the recommended presets-based sync path and then sweeps broader capabilities.
- `examples/console_basic/`: portable minimal console and JSON console output.
- `examples/text_formatter/`: portable text formatter and template example.
- `examples/style_tags/`: portable style tag and colored formatter example.
- `examples/file_rotation/`: target-sensitive file sink and rotation example with an explicit non-native skip path.
- `examples/config_build/`: portable config-driven `build_logger(...)` example.
- `examples/presets/`: portable-first presets example; adds file preset usage only when native file support is available.
- `examples/async_basic/`: native-only async logger example; the limitation is the `async fn main` entry path, not the absence of `src-async` compatibility APIs.
## Examples
## Documentation Entry Points
- `examples/console_basic/`: minimal console and JSON console example
- `examples/text_formatter/`: text formatting and template example
- `examples/style_tags/`: style tags and colored output example
- `examples/config_build/`: config-based build example
- `examples/presets/`: common preset combinations
- `examples/file_rotation/`: native file logging and rotation example
- `examples/async_basic/`: async logging example
- [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
- [Chinese README](../README.md)
## Documentation
- [API index](./api/index.md)
- [src package README](../src/README.mbt.md)
- Recommended sync starting APIs: `text_console(...)`, `file(...)`, `with_queue(...)`, `build_logger(...)`
- Selected API docs in `docs/api/`:
- [logger-new.md](./api/logger-new.md)
- [async-logger.md](./api/async-logger.md)
- [build-logger.md](./api/build-logger.md)
- [build-async-logger.md](./api/build-async-logger.md)
- [build-application-logger.md](./api/build-application-logger.md)
- [build-library-logger.md](./api/build-library-logger.md)
- [build-application-async-logger.md](./api/build-application-async-logger.md)
## Notes
- `docs/README-en.md` no longer acts as an API catalog.
- Detailed API references, config fields, runtime control helpers, and lifecycle surfaces now live under `docs/api/`.
- For concrete runnable flows, prefer `examples/`.
Common entry points: `text_console(...)`, `file(...)`, `with_queue(...)`, `build_logger(...)`, `build_async_logger(...)`