logleaf 1.0.0__tar.gz

logleaf-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 更新记录
+
+## 1.0.0 — 2026-09-24
+
+首次正式发行。
+
+### 功能
+
+- 提供共享入口 `log`、独立实例 `Logger` 和可绑定业务上下文的 `BoundLogger`。
+- 后台批量格式化和写入，文件与终端分别配置格式、等级和开关。
+- 支持 JSONL、可读文本、自由标量字段及异常堆栈。
+- 支持调用时刻或处理时刻采集、毫秒或微秒显示及可配置时区。
+- 提供有界队列、按等级统计的丢弃汇总和各输出的失败统计。
+- 支持文件大小轮转、进程独立文件、同步与异步关闭。
+
+### 兼容性与许可
+
+- 要求 Python 3.11+，运行时无第三方依赖。
+- 公开接口遵循 1.x 兼容约定；实验接口不在稳定范围内。
+- 采用 MIT 许可证。
+
+### 验证
+
+- macOS 与 Ubuntu 上的 Python 3.11、3.13 功能测试通过。
+- 发布流程检查源码包、wheel 元数据和安装后行为。
+- 性能测试采用合成负载；实际业务吞吐与延迟取决于运行环境和输出配置。

logleaf-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allen-zjx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logleaf-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include CHANGELOG.md PROTOTYPE.md requirements-dev.txt requirements-bench.txt
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include benchmarks *.py *.zip
+recursive-include reports *.md *.json

logleaf-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: logleaf
+Version: 1.0.0
+Summary: Bounded background logging with configurable outputs and loss accounting
+Author: Allen-zjx
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Allen-zjx/logleaf
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: loguru==0.7.3; extra == "benchmark"
+Requires-Dist: structlog==26.1.0; extra == "benchmark"
+Dynamic: license-file
+
+# logleaf
+
+轻量的 Python 结构化日志库。业务线程提交日志，后台线程完成字段合并、格式化和批量写入。
+
+**Python 3.11+ · 无第三方运行时依赖 · MIT 许可证**
+
+- 文件与终端分别开关、设置等级，支持 JSONL 和可读文本。
+- 用关键字参数添加业务字段，用 `bind()` 复用公共上下文。
+- 支持异常堆栈、文件轮转、毫秒或微秒时间显示。
+- 支持线程共享、异步关闭，并提供队列丢弃和输出失败统计。
+
+## 安装
+
+```bash
+python -m pip install logleaf
+```
+
+## 快速开始
+
+在程序入口初始化一次，退出前关闭：
+
+```python
+from logleaf import log
+
+log.init(
+    file_path="logs/app.jsonl",
+    console_enabled=True,
+)
+try:
+    log.info("程序启动")
+    log.info("任务完成", 耗时=120, 次数=3, 策略="策略A")
+finally:
+    log.close()
+```
+
+默认文件名带进程 PID，例如 `logs/app.12345.jsonl`。使用 `log.file_path` 获取实际路径。
+文件默认采用 JSONL，每行一条 JSON；终端采用文本，默认输出到 stderr。
+
+文件内容示例：
+
+```json
+{"timestamp":"2026-09-24T14:30:25.123456+08:00","timestamp_mode":"call","level":"INFO","event":"任务完成","耗时":120,"次数":3,"策略":"策略A"}
+```
+
+终端内容示例：
+
+```text
+2026-09-24 14:30:25.123456 | INFO | 任务完成 | 耗时=120 次数=3 策略=策略A
+```
+
+时间仅作格式示意。文本中的空格、分隔符和控制字符会按需加引号或转义。
+
+## 多个模块共享配置
+
+所有模块导入同一个 `log`，跟随程序入口的初始化配置。其他模块无需重复初始化：
+
+```python
+# worker.py
+from logleaf import log
+
+
+def run():
+    log.info("收到任务", task_id=123)
+```
+
+```python
+# main.py
+from logleaf import log
+from worker import run
+
+log.init(file_path="logs/app.jsonl", console_enabled=False)
+try:
+    run()
+finally:
+    log.close()
+```
+
+导入不会创建文件或启动后台线程。记录日志前必须调用 `log.init()`；重复初始化会报错。
+成功关闭后可以重新初始化，但之前的 `bind()` 对象仍属于旧实例，需要重新创建。
+
+## 自定义字段
+
+初始化后，可以按业务需要自由增减字段：
+
+```python
+log.info("任务完成", duration_us=120, attempts=3)
+
+strategy_log = log.bind(strategy="A", symbol="BTC")
+strategy_log.info("收到信号", signal="buy", price=60000)
+strategy_log.warning("重试", attempts=2)
+```
+
+字段值支持字符串、整数、有限浮点数、布尔值和 `None`。字典、列表和自定义对象不受支持。
+`duration_us`、`attempts` 等都是自定义字段，库不会自动计算耗时或推断单位。
+单条记录中的同名字段会覆盖绑定值，不影响后续记录。
+
+`timestamp`、`timestamp_mode`、`level`、`event`、`_log_hub` 是保留字段。
+
+## 记录异常
+
+在已初始化的日志上下文中，使用 `exception()` 记录当前异常：
+
+```python
+try:
+    result = 1 / 0
+except ZeroDivisionError:
+    log.exception("任务执行失败", task_id=123)
+```
+
+`exception()` 使用 ERROR 等级，支持异常原因链和异常组。JSONL 将异常详情放在
+`_log_hub` 中，仍保持每条一行；文本输出展开为多行堆栈。
+`error()` 只记录消息；在 `except` 外调用 `exception()` 时也不会附加堆栈。
+
+异常记录会在调用端采集位置和说明，后台完成格式化与写入；不采集局部变量，也不自动脱敏。
+
+## 文件与终端配置
+
+通过 `log.init()` 的参数控制输出。例如，文件保留 INFO 及以上，终端只显示 WARNING 及以上：
+
+```python
+log.init(
+    file_path="logs/app.jsonl",
+    file_level="INFO",
+    console_enabled=True,
+    console_level="WARNING",
+    timestamp_mode="call",
+    time_precision="us",
+    timezone="UTC",
+)
+```
+
+| 需求 | 配置 |
+|---|---|
+| 只写文件 | `console_enabled=False`，默认行为 |
+| 只显示终端 | `file_enabled=False, console_enabled=True` |
+| 文件保存为可读文本 | `file_format="text"` |
+| 终端输出 JSONL | `console_format="jsonl"` |
+| 显示毫秒 / 微秒 | `time_precision="ms"` / `"us"`，默认微秒 |
+| 使用调用时刻 / 后台处理时刻 | `timestamp_mode="call"` / `"worker"`，默认调用时刻 |
+| 设置时区 | `timezone="local"`、`"UTC"` 或 IANA 名称 |
+| 文件轮转 | `max_bytes=50 * 1024 * 1024, backup_count=5`，默认值 |
+| 限制队列容量 | `capacity=8192`，默认值 |
+
+日志始终带时间。`call` 模式在调用时采集，不受后续排队影响；`worker` 模式记录后台处理时刻。
+微秒显示精度不代表系统时钟保证微秒准确度。缺少 IANA 时区数据库的系统可安装 `tzdata`。
+
+## 异步程序
+
+在协程中直接调用 `log.info()`，退出时使用 `await log.aclose()`：
+
+```python
+import asyncio
+from logleaf import log
+
+
+async def main():
+    log.init(file_path="logs/async.jsonl")
+    try:
+        log.info("开始")
+        await asyncio.sleep(0.01)
+        log.info("完成")
+    finally:
+        await log.aclose()
+
+
+asyncio.run(main())
+```
+
+普通日志调用仍有参数处理和入队开销。`aclose()` 将等待后台排空的工作移到线程中，
+避免同步等待阻塞事件循环。
+
+## 独立日志实例
+
+需要不同输出或独立生命周期时使用 `Logger`：
+
+```python
+from logleaf import Logger
+
+with Logger("logs/orders.jsonl", console_enabled=True) as orders:
+    orders.info("订单创建", order_id="A001")
+```
+
+独立实例支持 `with` 和 `async with`，不会改变共享 `log` 的配置。
+多个线程可以共享一个实例；多进程应在每个子进程内部初始化，并分别写文件。
+
+## 队列、统计与关闭
+
+- 日志方法返回 `True` 表示已入队，尚不代表落盘；返回 `False` 表示被等级过滤、队列满或输出不可用。
+- 队列满时丢弃新记录，包括 ERROR/CRITICAL。后台会汇总丢弃数量；可读取 `log.stats.dropped`、`log.stats.pending` 和 `log.stats.outputs` 监控状态。
+- 文件或终端发生写入错误时，停用失败的输出，其他健康输出继续工作；关闭时会反馈错误。
+- `close()` / `aclose()` 默认最多等待 10 秒。正常关闭会排空队列并刷新缓冲，但不会执行 `fsync`。
+- 请显式关闭日志。强制结束进程或断电可能丢失尚未写完的内容。
+
+后台写入减少了调用端的工作，但仍会消耗 CPU，并受锁、GIL、磁盘和终端速度影响。
+不保证零开销、固定延迟上限或零丢失；需要逐条持久化保障的审计记录应使用专门的存储机制。
+
+## 文档
+
+本页涵盖常用用法。完整指南和可运行示例随 [PyPI 源码发行包](https://pypi.org/project/logleaf/#files) 提供：
+
+- `docs/usage.md`：完整配置、异常格式、统计与生命周期。
+- `docs/versioning.md`：公开接口和版本兼容约定。
+- `examples/`：同步、异步、多模块和多进程示例。
+- `CHANGELOG.md`：版本更新记录。
+
+## 许可证
+
+logleaf 采用 [MIT 许可证](https://spdx.org/licenses/MIT.html)。完整许可文本随安装包分发。

logleaf-1.0.0/PROTOTYPE.md

@@ -0,0 +1,103 @@
+# logleaf：日志性能实验
+
+这是早期性能原型的历史说明，不代表当前 `Logger` 的能力或推荐用法。
+原型源码位于 `src/logleaf/experimental/prototype.py`，仅用于复现实验；
+当前使用方式见 [README](README.md)，运行时仍只依赖标准库。
+
+本阶段要回答两个问题：调用日志能否更快返回；计入后台全部写完的时间后，整体是否更快。
+还要检查后台工作对其他 asyncio 任务的影响，以及队列带来的内存成本。
+
+本次结果：[性能表格与测试口径](reports/benchmark.md)、[结论和开发建议](reports/conclusion.md)。
+现有证据支持优先复用 structlog 前端、按需配置批量后端；尚不足以支持重写完整日志框架。
+
+## 运行实验
+
+需要 Python 3.11+，本次实测使用 CPython 3.13.5。依赖版本记录在
+`requirements-bench.txt` 中。以下命令在本仓库目录运行：
+
+```bash
+uv venv --python 3.13
+uv pip install --python .venv/bin/python -r requirements-bench.txt
+.venv/bin/pytest -q
+.venv/bin/ruff check src tests benchmarks
+TZ=UTC .venv/bin/python benchmarks/compare.py --count 30000 --rounds 3
+```
+
+测试自动创建、删除临时日志，最终生成 `reports/benchmark.json`（原始数据）和
+`reports/benchmark.md`（表格与方法说明）。`--execution-context` 可记录运行环境；
+正式测试使用 `--execution-context unsandboxed`，这个参数仅添加说明，不改变系统权限。
+本机初测发现沙箱会显著放大部分系统时间调用的成本，比较时应统一执行环境。
+
+## 比较对象
+
+| 名称 | 处理方式 |
+|---|---|
+| `stdlib_sync` | logging + 自定义缓冲 JSON 输出 Handler |
+| `stdlib_queue` | logging QueueHandler / QueueListener + 相同输出 Handler |
+| `loguru_sync` | Loguru + 自定义缓冲 JSON sink |
+| `loguru_queue` | 上一配置启用 `enqueue=True` |
+| `structlog_sync` | 原生过滤、缓存绑定 logger + 自定义缓冲 JSON sink |
+| `structlog_batch` | structlog 生成事件，接入本原型的批量写入后端 |
+| `prototype` | 本项目最小接口 + 相同批量写入后端 |
+
+这些都是针对本次输出需求配置的方案，不是各库的默认配置。
+相同数据字段和序列化器不意味着功能完全相同：例如 Loguru 仍收集额外元信息、
+其队列支持多进程；原型没有这些能力。不能把结果宣传为对成熟库的全面性能领先。
+
+吞吐量计算包含 drain、flush、close，并逐行检查字段、数量、顺序；不包含 fsync。
+正式性能组增大队列容量以避免丢弃，默认 8192 条容量的原型在持续超载时会丢弃新记录。
+队列满、慢写入、退出、写入失败等行为另有测试；不会把丢弃吞吐算作写入性能。
+标准库和第三方同步适配器使用 64 KiB 文件缓冲并在结束时 flush；原型另外周期 flush。
+本次未比较“每条日志立即可见”或“每条日志立即持久化”的场景。
+
+## 尝试原型
+
+可通过 `uv pip install --python .venv/bin/python -e .` 安装，或在源码目录使用
+`PYTHONPATH=src .venv/bin/python`。示例：
+
+```python
+from logleaf.experimental import BatchLogger
+
+with BatchLogger("app.jsonl", capacity=8192, batch_size=256) as log:
+    accepted = log.info("任务完成", task_id="task-123", elapsed_ms=12.5)
+    log.debug("调试信息")  # 默认 INFO 级别，此条被过滤
+    if not accepted:
+        # INFO 已开启时，False 表示队列满。由业务选择是否处理。
+        pass
+
+print(log.stats)  # 正常离开上下文时已排空并 flush
+```
+
+原型目前提供 `info()`、`debug()`、`log(level, event, **fields)`；等级数值为
+10/20/30/40/50。接受字符串、整数、有限浮点数、布尔值、None；拒绝列表、字典等
+可变对象，避免后台记录到对象后续修改后的值。`event`、`level`、`timestamp` 为保留字段。
+
+## 行为边界
+
+- 单进程、可多线程调用；不支持在 fork 后共享实例，也不协调多个进程写同一个文件。
+- 容量包含队列中和正在处理的记录。限制的是记录数量，不是总字节数。
+- 入队成功只代表被接受，不代表已经写入。队列满返回 False 并增加 `dropped`；
+  等级过滤也返回 False，但不增加 `dropped`。
+- 文件追加写入；默认最大批量 256，目标 flush 间隔 100 ms。调度、磁盘和大批次耗时
+  都可能延长这个间隔，不能视作严格的延迟上限。后台仍消耗 CPU，并可能竞争 GIL。
+- `stats.written` 是已交给文件流的条数，仍可能处于用户态缓冲；`close()` 成功才能确认
+  所有已接受日志完成 flush。`failed` 是写入器失败时未确认提交给文件流的条数；
+  若底层发生部分写入，文件可能含部分数据，不能据此实现精确重试。
+- `close()` 默认最多等待 10 秒，超时会抛异常，可以再次调用等待。超时不是强制终止
+  文件写入。关闭后的新日志、已发现的后台写入失败会抛异常，调用方可以明确发现故障。
+- 在 asyncio 中结束时使用 `await asyncio.to_thread(log.close)`，避免同步排空阻塞事件循环。
+- 需要显式关闭或使用上下文管理器；没有退出钩子。异常终止、断电可能丢失缓冲日志。
+  即使 flush 完成，也没有 fsync 持久化保证。
+- 尚未实现异常堆栈、上下文绑定、脱敏、轮转、通知桥接。启用这些功能后的性能需重新测量。
+
+## 如何决定下一步
+
+先比较 `prototype` 与 `structlog_batch`：如果接近，说明主要价值在写入后端，
+应优先复用成熟的日志前端；如果原型有稳定优势，再考虑保留轻量接口。
+同步 structlog 则用于检查“后台线程是否真的提高总吞吐”，防止只看入队速度。
+
+官方设计参考：
+
+- [structlog 性能指南](https://www.structlog.org/en/stable/performance.html)
+- [Loguru logger API](https://loguru.readthedocs.io/en/stable/api/logger.html)
+- [Python QueueHandler / QueueListener](https://docs.python.org/3/library/logging.handlers.html#queuehandler)

logleaf-1.0.0/README.md

@@ -0,0 +1,208 @@
+# logleaf
+
+轻量的 Python 结构化日志库。业务线程提交日志，后台线程完成字段合并、格式化和批量写入。
+
+**Python 3.11+ · 无第三方运行时依赖 · MIT 许可证**
+
+- 文件与终端分别开关、设置等级，支持 JSONL 和可读文本。
+- 用关键字参数添加业务字段，用 `bind()` 复用公共上下文。
+- 支持异常堆栈、文件轮转、毫秒或微秒时间显示。
+- 支持线程共享、异步关闭，并提供队列丢弃和输出失败统计。
+
+## 安装
+
+```bash
+python -m pip install logleaf
+```
+
+## 快速开始
+
+在程序入口初始化一次，退出前关闭：
+
+```python
+from logleaf import log
+
+log.init(
+    file_path="logs/app.jsonl",
+    console_enabled=True,
+)
+try:
+    log.info("程序启动")
+    log.info("任务完成", 耗时=120, 次数=3, 策略="策略A")
+finally:
+    log.close()
+```
+
+默认文件名带进程 PID，例如 `logs/app.12345.jsonl`。使用 `log.file_path` 获取实际路径。
+文件默认采用 JSONL，每行一条 JSON；终端采用文本，默认输出到 stderr。
+
+文件内容示例：
+
+```json
+{"timestamp":"2026-09-24T14:30:25.123456+08:00","timestamp_mode":"call","level":"INFO","event":"任务完成","耗时":120,"次数":3,"策略":"策略A"}
+```
+
+终端内容示例：
+
+```text
+2026-09-24 14:30:25.123456 | INFO | 任务完成 | 耗时=120 次数=3 策略=策略A
+```
+
+时间仅作格式示意。文本中的空格、分隔符和控制字符会按需加引号或转义。
+
+## 多个模块共享配置
+
+所有模块导入同一个 `log`，跟随程序入口的初始化配置。其他模块无需重复初始化：
+
+```python
+# worker.py
+from logleaf import log
+
+
+def run():
+    log.info("收到任务", task_id=123)
+```
+
+```python
+# main.py
+from logleaf import log
+from worker import run
+
+log.init(file_path="logs/app.jsonl", console_enabled=False)
+try:
+    run()
+finally:
+    log.close()
+```
+
+导入不会创建文件或启动后台线程。记录日志前必须调用 `log.init()`；重复初始化会报错。
+成功关闭后可以重新初始化，但之前的 `bind()` 对象仍属于旧实例，需要重新创建。
+
+## 自定义字段
+
+初始化后，可以按业务需要自由增减字段：
+
+```python
+log.info("任务完成", duration_us=120, attempts=3)
+
+strategy_log = log.bind(strategy="A", symbol="BTC")
+strategy_log.info("收到信号", signal="buy", price=60000)
+strategy_log.warning("重试", attempts=2)
+```
+
+字段值支持字符串、整数、有限浮点数、布尔值和 `None`。字典、列表和自定义对象不受支持。
+`duration_us`、`attempts` 等都是自定义字段，库不会自动计算耗时或推断单位。
+单条记录中的同名字段会覆盖绑定值，不影响后续记录。
+
+`timestamp`、`timestamp_mode`、`level`、`event`、`_log_hub` 是保留字段。
+
+## 记录异常
+
+在已初始化的日志上下文中，使用 `exception()` 记录当前异常：
+
+```python
+try:
+    result = 1 / 0
+except ZeroDivisionError:
+    log.exception("任务执行失败", task_id=123)
+```
+
+`exception()` 使用 ERROR 等级，支持异常原因链和异常组。JSONL 将异常详情放在
+`_log_hub` 中，仍保持每条一行；文本输出展开为多行堆栈。
+`error()` 只记录消息；在 `except` 外调用 `exception()` 时也不会附加堆栈。
+
+异常记录会在调用端采集位置和说明，后台完成格式化与写入；不采集局部变量，也不自动脱敏。
+
+## 文件与终端配置
+
+通过 `log.init()` 的参数控制输出。例如，文件保留 INFO 及以上，终端只显示 WARNING 及以上：
+
+```python
+log.init(
+    file_path="logs/app.jsonl",
+    file_level="INFO",
+    console_enabled=True,
+    console_level="WARNING",
+    timestamp_mode="call",
+    time_precision="us",
+    timezone="UTC",
+)
+```
+
+| 需求 | 配置 |
+|---|---|
+| 只写文件 | `console_enabled=False`，默认行为 |
+| 只显示终端 | `file_enabled=False, console_enabled=True` |
+| 文件保存为可读文本 | `file_format="text"` |
+| 终端输出 JSONL | `console_format="jsonl"` |
+| 显示毫秒 / 微秒 | `time_precision="ms"` / `"us"`，默认微秒 |
+| 使用调用时刻 / 后台处理时刻 | `timestamp_mode="call"` / `"worker"`，默认调用时刻 |
+| 设置时区 | `timezone="local"`、`"UTC"` 或 IANA 名称 |
+| 文件轮转 | `max_bytes=50 * 1024 * 1024, backup_count=5`，默认值 |
+| 限制队列容量 | `capacity=8192`，默认值 |
+
+日志始终带时间。`call` 模式在调用时采集，不受后续排队影响；`worker` 模式记录后台处理时刻。
+微秒显示精度不代表系统时钟保证微秒准确度。缺少 IANA 时区数据库的系统可安装 `tzdata`。
+
+## 异步程序
+
+在协程中直接调用 `log.info()`，退出时使用 `await log.aclose()`：
+
+```python
+import asyncio
+from logleaf import log
+
+
+async def main():
+    log.init(file_path="logs/async.jsonl")
+    try:
+        log.info("开始")
+        await asyncio.sleep(0.01)
+        log.info("完成")
+    finally:
+        await log.aclose()
+
+
+asyncio.run(main())
+```
+
+普通日志调用仍有参数处理和入队开销。`aclose()` 将等待后台排空的工作移到线程中，
+避免同步等待阻塞事件循环。
+
+## 独立日志实例
+
+需要不同输出或独立生命周期时使用 `Logger`：
+
+```python
+from logleaf import Logger
+
+with Logger("logs/orders.jsonl", console_enabled=True) as orders:
+    orders.info("订单创建", order_id="A001")
+```
+
+独立实例支持 `with` 和 `async with`，不会改变共享 `log` 的配置。
+多个线程可以共享一个实例；多进程应在每个子进程内部初始化，并分别写文件。
+
+## 队列、统计与关闭
+
+- 日志方法返回 `True` 表示已入队，尚不代表落盘；返回 `False` 表示被等级过滤、队列满或输出不可用。
+- 队列满时丢弃新记录，包括 ERROR/CRITICAL。后台会汇总丢弃数量；可读取 `log.stats.dropped`、`log.stats.pending` 和 `log.stats.outputs` 监控状态。
+- 文件或终端发生写入错误时，停用失败的输出，其他健康输出继续工作；关闭时会反馈错误。
+- `close()` / `aclose()` 默认最多等待 10 秒。正常关闭会排空队列并刷新缓冲，但不会执行 `fsync`。
+- 请显式关闭日志。强制结束进程或断电可能丢失尚未写完的内容。
+
+后台写入减少了调用端的工作，但仍会消耗 CPU，并受锁、GIL、磁盘和终端速度影响。
+不保证零开销、固定延迟上限或零丢失；需要逐条持久化保障的审计记录应使用专门的存储机制。
+
+## 文档
+
+本页涵盖常用用法。完整指南和可运行示例随 [PyPI 源码发行包](https://pypi.org/project/logleaf/#files) 提供：
+
+- `docs/usage.md`：完整配置、异常格式、统计与生命周期。
+- `docs/versioning.md`：公开接口和版本兼容约定。
+- `examples/`：同步、异步、多模块和多进程示例。
+- `CHANGELOG.md`：版本更新记录。
+
+## 许可证
+
+logleaf 采用 [MIT 许可证](https://spdx.org/licenses/MIT.html)。完整许可文本随安装包分发。