rlg-mcp

rlg

面向 Rust 的近乎无锁结构化日志记录：记录只需经过几次原子操作，就会离开应用线程，随后由后台刷新器进行格式化并写入。

---

目录

开始使用

• 安装 — 库使用 Cargo 安装，CLI 和 MCP 服务使用 cargo install
• 要求 — 工具链最低要求、平台
• 快速开始 — 记录并刷新一条结构化记录

rlg 生态系统

• rlg 生态系统 — rlg、rlg-cli、rlg-report、rlg-mcp、rlg-otlp、rlg-redact、rlg-tower、rlg-test、rlg-wasm、rlg-ebpf

库参考

• 功能一览 — 当前功能概览
• 生态系统对比 — 简要矩阵；完整表格见 docs/COMPARISON.md
• 基准测试 — 关键数据；完整表格见 docs/BENCHMARKS.md
• 功能 — 模块级功能列表
• 配置 — 核心选项
• 示例 — 可运行示例索引

运维

• 何时不应使用 rlg — 局限性
• 开发 — make 目标、模糊测试、CI
• 安全 — 保证与合规性
• 文档 — 所有参考文档
• 稳定性保证 — SemVer 维度、输出稳定性、最低工具链要求
• 许可证

---

安装

作为 Rust 库

[dependencies]
rlg = "0.0.15"

配套项目的安装方式相同，且版本一致：

[dependencies]
rlg-otlp   = "0.0.15"  # ship records to an OpenTelemetry Collector
rlg-tower  = "0.0.15"  # per-request access logs for tower services
rlg-redact = "0.0.15"  # scrub secrets and PII before they are written

[dev-dependencies]
rlg-test   = "0.0.15"  # assert on captured records in tests

命令行工具

cargo install rlg-cli      # `rlg`: filter and convert log files
cargo install rlg-report   # `rlg-report`: summaries by level, component and message
cargo install rlg-mcp      # `rlg-mcp`: log files as tools for AI agents

在检出代码后，make install 会构建三个二进制文件，并将它们及其 man 手册页和 bash、zsh、fish 补全文件安装到 /usr/local 下（遵循 PREFIX 和 DESTDIR；make uninstall 可撤销安装）。这些二进制文件也可以生成各自的文件： rlg --manpage > rlg.1、rlg --completions zsh > _rlg。

rlg-mcp 也以容器映像的形式发布，地址为 ghcr.io/sebastienrousseau/rlg-mcp，并已列入 MCP 注册表。

---

要求

• Rust 1.88.0 或更高版本（edition 2024）。CI 会在 1.88.0 上构建每个库和二进制文件；请参阅工具链政策。
• 原生输出目标（os_log、journald）需要 macOS 或 Linux。 在其他所有平台（包括 Windows）上，rlg 都会写入文件或标准输出。

---

快速开始

use rlg::log::Log;
use rlg::log_format::LogFormat;

fn main() {
    // Keep the guard for the life of the program: dropping it flushes
    // pending records and stops the background thread.
    let _guard = rlg::init().unwrap();

    Log::info("User authenticated")
        .component("auth-service")
        .with("user_id", 42)
        .format(LogFormat::JSON)
        .fire();
}

fire() 会检查级别，将记录推入环形缓冲区，然后返回；刷新线程会将其格式化为 JSON，并写入平台输出目标。此代码块会由 cargo test 编译并运行。

---

rlg 生态系统

十个 crate 采用相同版本 0.0.15，并一同发布。

组件	用途	使用场景
rlg	引擎：65,536 槽位环形缓冲区、后台刷新器、14 种格式、原生输出目标	任意 Rust 程序中的结构化日志记录
rlg-cli	rlg 二进制文件：按级别、组件或属性筛选，在不同格式间转换	my-service | rlg --min-level error --format ecs
rlg-report	rlg-report 二进制文件和库：按级别和组件统计数量、热门消息、延迟百分位数	值班故障排查、每日错误摘要
rlg-mcp	MCP 服务：通过 stdio、可流式传输的 HTTP 或 HTTP+SSE 提供四个工具、一个提示词、两个资源	AI Agent 读取生产环境日志
rlg-otlp	向本地 OpenTelemetry Collector 导出的 OTLP/HTTP	通过 Collector 接入 Honeycomb、Datadog、Grafana
rlg-redact	一次性清除银行卡号、JWT、Bearer 令牌、电子邮件地址、IPv4 地址和 AWS 密钥	GDPR 合规与审计跟踪安全
rlg-tower	tower::Layer：每个请求生成一条访问日志记录	axum、hyper 和其他 tower 服务
rlg-test	在测试中捕获记录并对其进行断言	测试自身日志输出的库
rlg-wasm	wasm-bindgen 绑定和 WASI 0.2 组件接口	浏览器、Deno、Workers、wasmtime 宿主
rlg-ebpf	可移植的进程增强；Linux 上的 eBPF 增强器脚手架	为每条记录添加主机上下文

---

功能一览

领域	功能	状态
数据摄取	原子级别筛选、环形缓冲区推送、调用线程不加锁	稳定
格式	JSON、NDJSON、ECS、GELF、Logstash、OTLP、MCP、logfmt、CLF、CEF、ELF、W3C、Apache、Log4j XML	稳定
输出目标	os_log（macOS）、journald（Linux）、文件、标准输出	稳定
输出目标	io_uring 文件输出目标（Linux，uring 功能）	脚手架
配置	TOML 加载、验证、轮询热重载（tokio 功能）	稳定
桥接	通过 rlg::init() 接入 log facade；tracing 层（tracing-layer 功能）	稳定
导出	向本地 Collector 导出的 OTLP/HTTP（rlg-otlp）	稳定
Agent	通过 stdio、可流式传输的 HTTP 和 HTTP+SSE 提供的 MCP 服务（rlg-mcp）	稳定
增强	eBPF 内核上下文（rlg-ebpf，Linux）	脚手架

---

生态系统对比

rlg 放弃 tracing 的 span 模型，采用仅包含事件的引擎，将格式化和 I/O 操作移出应用线程，并内置原生输出目标、多种格式和 Agent 接口。

项目	在调用线程之外格式化	内置格式	原生 journald / os_log
rlg	是	14	是
tracing + tracing-subscriber	附加组件	text、JSON	附加组件
slog	附加组件	附加组件	附加组件
log + env_logger	否	text	否

证据和完整对照表请参阅 docs/COMPARISON.md。

---

基准测试

competitive_bench 套件会对比 rlg 的 fire() 与 tracing::info! 和 log::info!，测试单条记录、带属性的记录、 10,000 条记录的突发写入以及延迟分布。该套件会在每个发布标签对应的 CI 中运行，结果作为工作流构建产物发布。

场景	结果	环境
rlg fire()，一条记录	598 ns	GitHub 托管的 ubuntu-latest，release 配置
tracing::info! 写入丢弃型写入器	591 ns	同一次运行
rlg fire()，带 3 个属性	947 ns（tracing：1,117 ns）	同一次运行

在调用线程上，rlg 现在的开销与 tracing 大致相当，而且不会在该线程上进行 格式化；它带来的好处是调用方不会等待接收端的 I/O。

方法和完整结果请参阅 docs/BENCHMARKS.md。

---

功能

所有功能默认均为可选且关闭。

功能	Crate	提供内容
tokio	rlg	Config::load_async 和轮询式热重载
tui	rlg	实时终端仪表板，通过 RLG_TUI=1 启动
tracing-layer	rlg	RlgLayer，一个 tracing_subscriber::Layer
fast-queue	rlg	用于多个并发生产者的八分片环形缓冲区
uring	rlg	Linux 上的 io_uring 文件接收端
async	rlg-otlp	基于 Tokio 的 AsyncOtlpExporter

---

配置

Config 从 TOML 加载配置并进行验证，然后创建所需的日志路径。

# rlg.toml
version              = "1.0"
profile              = "production"
log_file_path        = "/var/log/rlg.log"
log_level            = "INFO"
logging_destinations = [
    { type = "File", value = "/var/log/rlg.log" },
    { type = "Stdout" },
]
log_rotation         = { Size = 10485760 }  # 10 MiB

使用 Config::load(Some("rlg.toml")) 加载，或者启用 tokio 功能后使用 Config::load_async，并通过 Config::hot_reload_async 跟踪编辑变更。RUST_LOG 也可以设置日志级别。 Crate README 列出了所有字段。

---

示例

示例	展示内容	运行命令
example_log_format	并排展示全部 14 种格式	cargo run -p rlg --example example_log_format
example_config	TOML 配置、异步加载、热重载	cargo run -p rlg --example example_config --features tokio
example_macros	日志宏	cargo run -p rlg --example example_macros
serve_a_session	针对 rlg-mcp 的完整 MCP 会话	cargo run -p rlg-mcp --example serve_a_session
honeycomb	通过本地 Collector 导出	cargo run -p rlg-otlp --example honeycomb

CI 会在每个拉取请求中运行所有示例（examples-smoke.yml），但不包括 example_config 和 example_utils，这两个异步示例的行为已由 crate 自身的测试覆盖。

---

不适合使用 rlg 的情况

• 日志量低。 每秒记录数低于约一百条时，后台线程和 65k 槽缓冲区 并不能带来同步日志记录器无法提供的好处。
• 以 Span 为核心模型。 rlg 记录事件。如果你分析的是层级 Span， 请直接使用 tracing；rlg 的层仅用于桥接其事件。
• Windows 事件日志。 没有原生 Windows 接收端；rlg 在 Windows 上会写入 文件或标准输出。
• 必须确保每条记录在崩溃后仍然保留。 记录会一直在内存中等待写入器写入； 如果进程在 FlushGuard 析构前被终止，仍在缓冲区中的记录就会丢失。
• 需要稳定的 API。 rlg 目前处于 0.0.x 阶段：任何版本都可能带来破坏性变更， 且只有一位维护者。

---

开发

make verify   # everything CI runs on a pull request
make demo     # re-render .github/demo.gif from .github/demo.tape

DEVELOPMENT.md 列出了每项检查及其本地运行命令：用于引擎并发性和内存安全的 Miri、Loom 和 Kani，四个模糊测试目标，用于依赖树检查的 cargo-deny 和 cargo-vet，cargo-semver-checks、95% 的覆盖率下限以及复杂度上限。 贡献和签名规则见 CONTRIBUTING.md 和 AGENTS.md。

---

安全

• 漏洞报告：请通过电子邮件或 GitHub 的安全公告表单私下报告；切勿在公开议题中报告。处理流程和响应时间见 SECURITY.md。
• 内存安全：除 crates/rlg/src/sink.rs 中有文档说明的 macOS os_log FFI 外，整个工作区均禁止使用 unsafe。每次推送时都会在 Miri 下运行引擎。
• 资源限制：环形缓冲区最多容纳 65,536 条记录，满时会淘汰最旧的记录；rlg-otlp 将采集器的响应头限制为 16 KiB，并为每个请求设置超时。
• 模糊测试：每个拉取请求都会运行 4 个 cargo-fuzz 目标（记录解析、格式名称、配置加载、脱敏）；OSS-Fuzz 状态见 docs/OSS-FUZZ.md。
• 供应链：每个依赖项都会通过 cargo-deny 和 cargo-vet 检查；发布通过 crates.io Trusted Publishing 进行，并附带 sigstore 签名的 SBOM（pkg/VERIFY.md）。

请按照 SECURITY.md 报告漏洞。

---

文档

文档	适用内容
用户手册	教程、操作指南、架构、ADR（源文件）
API 参考	docs.rs 上各个 crate 的所有公开条目
DEVELOPMENT.md	工具链、本地检查项、测试布局、发布模式
docs/ARCHITECTURE.md	引擎和卫星组件如何协同工作
CHANGELOG.md	各个版本的变更内容
迁移指南	从 log、slog 或 tracing 迁移

---

稳定性保证

• SemVer 规则：rlg 目前处于 0.0.x 阶段，因此按照 Cargo 的规则，每个版本都可能包含破坏性变更。破坏性变更会在 CHANGELOG 中标记为 Breaking，并且每个拉取请求都会运行 cargo-semver-checks，确保此类变更不会在未声明的情况下悄然发布。
• 输出稳定性：格式生成的字节内容属于接口。即使没有签名变动，同一条记录的输出发生变化也属于破坏性变更，并会以相同方式记录。
• 最低工具链版本：Rust 1.88.0，并在 CI 中强制执行；提高最低版本时，会在 CHANGELOG 中单独记录变更及其原因。完整政策见 docs/POLICIES.md。

---

许可证

采用以下任一许可证进行双重许可：

• Apache License, Version 2.0（LICENSE-APACHE）
• MIT license（LICENSE-MIT）

由你选择。除非另有说明，你为纳入 rlg 而提交的任何贡献，均按上述双重许可授权，不附加任何条款。