QuantumLog

QuantumLog 是一个为高性能计算场景打造的异步日志库，支持文件、标准输出、数据库等多种输出目标，提供灵活的配置选项、优雅的关闭机制以及详细的诊断能力。

🚀 核心特性

异步高性能：基于 Tokio 的异步架构，支持高并发日志写入
多输出目标：支持 stdout、文件、数据库等多种输出方式
灵活配置：支持 TOML 配置与代码方式配置
优雅关闭：完善的关闭机制，确保日志不丢失
诊断能力：内置诊断信息，便于监控日志系统性能
MPI 支持：面向 HPC 环境优化，支持 MPI
背压处理：高负载下的智能背压处理
结构化日志：支持结构化日志与多种输出格式

📦 安装

在你的 Cargo.toml 中添加依赖：

[dependencies]
quantum_log = "0.3.0"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"

# 可选特性（示例）
[dependencies.quantum_log]
version = "0.3.0"
features = ["database", "mpi_support"]  # 启用数据库与 MPI 支持

🎯 快速开始

基础用法

use quantum_log::{init, shutdown};
use tracing::{info, warn, error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化 QuantumLog
    init().await?;

    // 使用标准 tracing 宏
    info!("应用启动");
    warn!("这是一个警告");
    error!("这是一个错误");

    // 优雅关闭
    shutdown().await?;
    Ok(())
}

使用设计文档推荐的主 API

use quantum_log::init_quantum_logger;
use tracing::{info, warn, error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 使用设计文档推荐的主 API
    let shutdown_handle = init_quantum_logger().await?;

    info!("正在使用 QuantumLog 记录日志");
    warn!("警告信息");
    error!("错误信息");

    // 使用返回的句柄优雅关闭
    shutdown_handle.shutdown().await?;
    Ok(())
}

🆕 0.3.0 变更日志

QuantumLog 0.3.0 带来更强大的功能与更好的稳定性，主要变更：

Zero dead_code 警告：移除所有编译告警，构建更干净
MPI 动态加载：在运行时加载 MPI 库，提升部署灵活性
文档改进：统一 feature 名称并修正示例
加强错误处理：更精确的错误分类与处理

迁移提示（MPI 动态加载）：自 0.3.0 起，运行时代码不再读取自定义 MPI_LIB_PATH。请使用平台标准环境变量（LD_LIBRARY_PATH/PATH/DYLD_LIBRARY_PATH）覆盖或指定库路径。MPI_LIB_PATH 仅在构建阶段作为信息展示，运行时不依赖该变量。

🔧 启用 MPI 动态加载

QuantumLog 支持在运行时动态加载 MPI 库，无需在编译期进行静态/动态链接。启用方式：

[dependencies.quantum_log]
version = "0.3.0"
features = ["mpi_support", "dynamic_mpi"]

亮点：

运行时检测：启动时自动检测可用的 MPI 库
跨平台支持：适配不同系统的库文件命名
- Linux: libmpi.so, libmpi.so.12, libmpi.so.40
- Windows: mpi.dll
- macOS: libmpi.dylib
灵活部署：构建环境无需安装 MPI 开发包
优雅降级：当 MPI 不可用时自动禁用相关功能，程序继续运行

示例：

use quantum_log::init_quantum_logger;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let handle = init_quantum_logger().await?;
    tracing::info!("程序已启动；MPI 支持由运行时环境决定");
    handle.shutdown().await?;
    Ok(())
}

库查找配置：系统按以下顺序查找 MPI 动态库：

标准系统路径：系统默认的库搜索路径
环境变量路径：LD_LIBRARY_PATH（Linux）、PATH（Windows）、DYLD_LIBRARY_PATH（macOS）
构建期检测到的常见安装路径：
- /usr/lib/x86_64-linux-gnu/openmpi/lib
- /usr/lib64/openmpi/lib
- /opt/intel/oneapi/mpi/latest/lib
- /usr/local/lib

如需指定自定义库路径，请配置相应的系统环境变量。

注意：使用动态加载时，请确保目标系统已安装兼容的 MPI 运行时。

环境变量与路径覆盖：

运行时动态加载遵循系统库搜索路径与常见库名；当前实现不直接读取自定义 MPI_LIB_PATH 运行时变量。
如需覆盖或指定特定库位置，请在启动前配置：
- Linux: export LD_LIBRARY_PATH=/path/to/mpi/lib:$LD_LIBRARY_PATH
- macOS: export DYLD_LIBRARY_PATH=/path/to/mpi/lib:$DYLD_LIBRARY_PATH
- Windows（PowerShell）: $env:PATH = "C:\\Path\\to\\MPI\\bin;" + $env:PATH
构建阶段如检测到常见目录，会通过 MPI_LIB_PATH 输出构建环境信息，但运行时不依赖该变量。

平台指引：

Linux（推荐 OpenMPI 或 MPICH）：
- Ubuntu/Debian: sudo apt-get install libopenmpi-dev openmpi-bin 或 sudo apt-get install mpich
- CentOS/RHEL: sudo yum install openmpi openmpi-devel 或 sudo yum install mpich
Windows（MS-MPI）：
- 安装 Microsoft MPI（MS-MPI）Runtime 与 SDK，并确保包含 mpi.dll 的目录在 PATH 中
- 常见路径示例：C:\\Program Files\\Microsoft MPI\\Bin
macOS（Homebrew OpenMPI）：
- brew install open-mpi，并在必要时将 $(brew --prefix)/lib 加入 DYLD_LIBRARY_PATH

🧪 测试

运行测试：

# 运行全部测试
cargo test

# 按特性运行测试
cargo test --features database
cargo test --features mpi_support

# 运行示例
cargo run --example basic_usage
cargo run --example complete_examples
cargo run --example config_file_example

📝 许可证

本项目基于 Apache-2.0 许可证发布。详见 LICENSE。

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解如何参与项目开发。

📞 支持

如果你遇到问题或有建议，请：

查看在线文档
在 GitHub 上搜索或创建 Issue
参与 Discussions

quantum_log 0.3.0