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 を実行すると、3 つのバイナリをビルドし、man ページおよび bash、zsh、fish の補完とともに /usr/local にインストールします（PREFIX と DESTDIR に対応しており、make uninstall で元に戻せます）。バイナリは、それぞれ自身の man ページと補完ファイルを生成できます。 rlg --manpage > rlg.1、rlg --completions zsh > _rlg。

rlg-mcp はコンテナイメージ ghcr.io/sebastienrousseau/rlg-mcp としても公開されており、MCP レジストリにも登録されています。

---

要件

• Rust 1.88.0 以降（エディション 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 エコシステム

10 個のクレートは 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 経由で 4 つのツール、1 つのプロンプト、2 つのリソースを提供	本番ログを読み取る AI エージェント
rlg-otlp	ローカルの OpenTelemetry Collector への OTLP/HTTP エクスポーター	Collector 経由での Honeycomb、Datadog、Grafana
rlg-redact	カード番号、JWT、ベアラートークン、メールアドレス、IPv4 アドレス、AWS キーを 1 回の処理で除去	GDPR および監査証跡の保護
rlg-tower	リクエストごとに 1 件のアクセスログレコードを出力する 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 ファサード；tracing レイヤー（tracing-layer 機能）	安定
エクスポート	ローカルの Collector への OTLP/HTTP（rlg-otlp）	安定
エージェント	stdio、ストリーム可能な HTTP、HTTP+SSE 経由の MCP サーバー（rlg-mcp）	安定
エンリッチメント	eBPF カーネルコンテキスト（rlg-ebpf、Linux）	ひな形

---

エコシステムの比較

rlg は tracing のスパンモデルではなくイベント専用エンジンを採用しています。フォーマット処理と I/O をアプリケーションスレッドの外部で行い、ネイティブシンク、多数の形式、エージェントインターフェースを標準で提供します。

プロジェクト	呼び出し元スレッド外でのフォーマット処理	組み込み形式	ネイティブ journald / os_log
rlg	はい	14	はい
tracing + tracing-subscriber	アドオン	テキスト、JSON	アドオン
slog	アドオン	アドオン	アドオン
log + env_logger	いいえ	テキスト	いいえ

根拠と完全な比較表については、docs/COMPARISON.mdをご覧ください。

---

ベンチマーク

competitive_bench スイートでは、単一レコード、属性付きレコード、10,000 レコードのバースト、およびレイテンシ分布について、rlg の fire() と tracing::info!、log::info! の実行時間を測定します。すべてのリリースタグで CI が実行し、結果はワークフローの アーティファクトとして公開されます。

シナリオ	結果	環境
rlg fire()、1 レコード	598 ns	GitHub-hosted ubuntu-latest、リリースプロファイル
tracing::info!、破棄するライターへの出力	591 ns	同じ実行
rlg fire()、属性 3 個	947 ns（tracing：1,117 ns）	同じ実行

呼び出し側のスレッドでの rlg のコストは、そこでフォーマットを行わずに tracing とほぼ同程度になりました。その代わり、呼び出し側がシンクの I/O を待つことはありません。

手法と全結果については、docs/BENCHMARKS.md を参照してください。

---

機能

すべての機能はデフォルトでオフです。

機能	クレート	追加内容
tokio	rlg	Config::load_async とポーリングによるホットリロード
tui	rlg	RLG_TUI=1 で起動するライブターミナルダッシュボード
tracing-layer	rlg	tracing_subscriber::Layer である RlgLayer
fast-queue	rlg	多数の並行プロデューサー向けの 8 シャードのリングバッファー
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 でもレベルを設定できます。 すべてのフィールドについてはクレートの 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 は、非同期デモであり、クレート独自のテストで動作を検証できる example_config と example_utils を除き、すべてのプルリクエストで各使用例を実行します（examples-smoke.yml）。

---

rlg を使わないほうがよい場合

• ログ量が少ない場合。 1 秒あたり約 100 レコード未満では、バックグラウンドスレッドと 65k スロットのバッファーを導入しても、同期ロガーで得られるもの以上の利点はありません。
• スパンをモデルとしている場合。 rlg が記録するのはイベントです。分析対象が階層的なスパンである場合は、tracing を直接使用してください。rlg のレイヤーはイベントを橋渡しするだけです。
• Windows イベントログを使う場合。 ネイティブの Windows シンクはありません。rlg は Windows ではファイルまたは stdout に書き込みます。
• すべてのレコードをクラッシュ後も保持する必要がある場合。 レコードはフラッシャーが書き込むまでメモリ上で待機します。FlushGuard がドロップする前にプロセスが強制終了されると、バッファーに残っているデータは失われます。
• 安定した API が必要な場合。 rlg は 0.0.x のため、どのリリースでも互換性が失われる可能性があり、メンテナーは 1 人です。

---

開発

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、4 つのファズターゲット、依存関係ツリー向けの cargo-deny と cargo-vet、cargo-semver-checks、カバレッジの下限 95％、複雑さの上限など、すべてのチェックとローカルで実行するコマンドが記載されています。 コントリビューションと署名のルールは、CONTRIBUTING.md と AGENTS.md に記載されています。

---

セキュリティ

• 報告：メールまたは GitHub のアドバイザリーフォームから非公開で報告してください。公開 issue では報告しないでください。手順と対応時間は 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 に掲載されている、各クレートのすべての公開項目
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 への収録を目的として提出されたすべてのコントリビューションは、追加条件なしで上記のデュアルライセンスのもとで提供されます。