Secra Logger
一个生产级的 Rust 日志系统库,基于 tracing 生态系统构建。

特性
- ✅ 基于 tracing 生态,支持结构化日志
- ✅ JSON 格式输出(基于 tracing-subscriber)
- ✅ 支持控制台、文件、或同时输出
- ✅ 可配置的控制台彩色输出
- ✅ 线程安全
- ✅ 支持 log crate 桥接
- ✅ 支持 actix-web 集成
- ✅ 高性能异步写入
- ✅ 字段规范化支持(遵循 OpenTelemetry 语义约定)
- ✅ Request ID 注入支持
- ✅ Logrotate 配置生成支持
- ✅ Vector 日志收集器配置支持
安装
在 Cargo.toml 中添加依赖:
[dependencies]
secra-logger = "1.0"
快速开始
基本使用
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
use tracing::{info, error, warn, debug};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
logging_module.init(Some(config))?;
info!("应用启动");
error!("发生错误");
warn!("警告信息");
debug!("调试信息(不会输出,因为级别是 INFO)");
Ok(())
}
使用默认配置
use secra_logger::{LoggingModule, LoggingConfig};
use tracing::info;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let logging_module = LoggingModule::new();
logging_module.init(None)?;
info!("使用默认配置记录日志");
Ok(())
}
结构化日志
secra-logger 完全支持 tracing 的结构化日志功能:
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
use tracing::info;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
logging_module.init(Some(config))?;
let user_id = 12345;
let action = "login";
info!(
user_id = user_id,
action = action,
ip = "192.168.1.1",
duration_ms = 150,
"用户登录成功"
);
info!(
user_id = user_id,
"用户 {} 执行了操作", user_id
);
Ok(())
}
输出示例(JSON 格式):
{
"timestamp": "2024-01-15T10:30:45.123456789+08:00",
"level": "INFO",
"fields": {
"message": "用户登录成功",
"user_id": 12345,
"action": "login",
"ip": "192.168.1.1",
"duration_ms": 150
},
"target": "myapp",
"file": "src/main.rs",
"line": 86
}
错误处理
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
fn main() {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::File,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: None,
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
match logging_module.init(Some(config)) {
Ok(()) => {
tracing::info!("日志系统初始化成功");
}
Err(e) => {
eprintln!("初始化失败: {}", e);
}
}
}
多线程使用
secra-logger 是线程安全的,可以在多线程环境中安全使用:
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
use std::thread;
use tracing::info;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
logging_module.init(Some(config))?;
let handles: Vec<_> = (0..5)
.map(|i| {
thread::spawn(move || {
for j in 0..10 {
info!(
thread_id = i,
iteration = j,
"线程 {} 执行第 {} 次迭代", i, j
);
}
})
})
.collect();
for handle in handles {
handle.join().unwrap();
}
Ok(())
}
Actix-Web 集成
use actix_web::{web, App, HttpServer, Responder};
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
use tracing::info;
#[actix_web::main]
async fn main() -> std::io::Result<()> {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/webapp.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
logging_module.init(Some(config)).expect("初始化日志系统失败");
info!("Web 服务器启动中...");
HttpServer::new(|| {
App::new()
.route("/", web::get().to(|| async { "Hello, World!" }))
})
.bind("127.0.0.1:8080")?
.run()
.await
}
使用 log crate 兼容接口
如果你需要使用传统的 log crate API,secra-logger 也提供了桥接支持:
use secra_logger::{LoggingModule, LoggingConfig, OutputMode};
use log::{info, error, warn};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let logging_module = LoggingModule::new();
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
logging_module.init(Some(config))?;
info!("使用 log crate 记录日志");
warn!("警告信息");
error!("错误信息");
Ok(())
}
配置说明
LoggingConfig
LoggingConfig 是日志系统的核心配置结构:
pub struct LoggingConfig {
pub level: String, pub output_mode: OutputMode, pub file: Option<LogFileConfig>, pub console: Option<LogConsoleConfig>, pub enable_request_id: bool, pub fields: LogFieldsConfig, pub vector: Option<VectorConfig>, }
创建配置
使用 LoggingConfig::default() 创建默认配置:
let config = LoggingConfig::default();
或者手动创建配置:
use secra_logger::{LoggingConfig, OutputMode};
let config = LoggingConfig {
level: "info".to_string(),
output_mode: OutputMode::Both,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: Some(secra_logger::LogConsoleConfig {
enabled: true,
ansi: true,
}),
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
配置验证
配置对象提供了 validate() 方法用于验证配置的有效性:
let config = LoggingConfig {
level: "invalid".to_string(), output_mode: OutputMode::File,
file: Some(secra_logger::LogFileConfig {
path: "./logs/app.log".to_string(),
enabled: true,
logrotate: None,
}),
console: None,
enable_request_id: true,
fields: secra_logger::LogFieldsConfig::default(),
vector: None,
};
if let Err(e) = config.validate() {
eprintln!("配置验证失败: {}", e);
}
OutputMode
OutputMode 枚举定义了日志的输出模式:
OutputMode::File - 仅输出到文件(适合生产环境)
OutputMode::Console - 仅输出到控制台(适合开发环境)
OutputMode::Both - 同时输出到文件和控制台(适合需要同时查看和保存的场景)
LogFileConfig
文件输出配置:
pub struct LogFileConfig {
pub path: String, pub enabled: bool, pub logrotate: Option<LogrotateConfig>, }
LogConsoleConfig
控制台输出配置:
pub struct LogConsoleConfig {
pub enabled: bool, pub ansi: bool, }
LogFieldsConfig
字段规范化配置:
pub struct LogFieldsConfig {
pub enabled: bool, pub mappings: HashMap<String, String>, }
字段规范化遵循 OpenTelemetry 语义约定:
- HTTP 请求:
http.method, http.path, http.status_code
- 数据库:
db.system, db.name, db.operation
- 服务:
service.name, service.version
- 请求追踪:
trace_id, span_id, request_id
- 用户:
user.id, user.email
LogrotateConfig
Logrotate 配置用于生成 logrotate 配置文件,以便系统自动管理日志文件。
注意:使用 logrotate 功能前,需要先在系统上安装 logrotate 工具。详细安装教程请参考 Logrotate 安装指南。
pub struct LogrotateConfig {
pub enabled: bool, pub path: String, pub rotate: String, pub size: Option<String>, pub maxsize: Option<String>, pub minsize: Option<String>, pub rotate_count: u32, pub maxage: Option<u32>, pub start: u32, pub compress: bool, pub delaycompress: u32, pub compresscmd: Option<String>, pub uncompresscmd: Option<String>, pub compressext: String, pub compressoptions: Option<String>, pub create: bool, pub create_mode: String, pub create_owner: Option<String>, pub copy: bool, pub copytruncate: bool, pub postrotate: bool, pub postrotate_script: Option<String>, pub prerotate: bool, pub prerotate_script: Option<String>, pub firstaction: bool, pub firstaction_script: Option<String>, pub lastaction: bool, pub lastaction_script: Option<String>, pub missingok: bool, pub notifempty: bool, pub ifempty: bool, pub sharedscripts: bool, pub dateext: bool, pub dateformat: String, pub olddir: Option<String>, pub noolddir: bool, pub extension: Option<String>, pub tabooext: Vec<String>, pub su: Option<String>, pub mail: bool, pub mailfirst: Option<String>, pub maillast: bool, pub nomail: bool, pub include: Vec<String>, pub shred: bool, pub shredcycles: u32, pub nocompress: bool, }
LogrotateConfig 配置选项说明
轮转策略:
rotate: 轮转周期(daily/weekly/monthly/yearly/size)
size: 文件大小限制,当日志文件达到此大小时进行轮转
minsize: 最小文件大小,小于此大小的文件不进行轮转
rotate_count: 保留的日志文件数量
maxage: 最大保留天数,超过此天数的旧日志将被删除
start: 起始轮转编号(默认从 1 开始)
压缩选项:
compress: 是否压缩旧日志文件
delaycompress: 压缩延迟(轮转后 N 个周期再压缩)
compresscmd: 压缩命令(默认 gzip)
uncompresscmd: 解压缩命令(默认 gunzip)
compressext: 压缩文件扩展名(默认 .gz)
compressoptions: 压缩选项(如 -9 表示最高压缩级别)
nocompress: 是否不压缩(与 compress 相反)
文件创建:
create: 是否在轮转时创建新文件
create_mode: 新文件的权限(八进制格式,如 0644)
create_owner: 新文件的所有者(user:group)
copy: 是否使用 copy 模式(复制原文件后截断)
copytruncate: 是否使用 copytruncate 模式(复制后截断原文件)
脚本执行:
prerotate/prerotate_script: 轮转前执行的脚本
postrotate/postrotate_script: 轮转后执行的脚本
firstaction/firstaction_script: 第一次轮转前执行的脚本
lastaction/lastaction_script: 最后一次轮转后执行的脚本
sharedscripts: 是否共享脚本(多个日志文件共享一个脚本)
su: 以指定用户身份运行脚本(user:group)
文件处理:
missingok: 是否忽略缺失的日志文件
notifempty: 是否在日志文件为空时不轮转
ifempty: 是否即使文件为空也轮转(与 notifempty 相反)
olddir: 旧日志文件目录(用于将旧日志移动到指定目录)
noolddir: 是否不使用 olddir
extension: 压缩文件扩展名
tabooext: 禁止的扩展名列表(这些扩展名的文件不会被轮转)
日期格式:
dateext: 是否使用日期扩展名(默认使用数字扩展名 .1, .2, ...)
dateformat: 日期扩展名格式(默认 %Y%m%d,如 .20260114)
邮件通知:
mail: 是否发送邮件通知
mailfirst: 邮件地址(轮转前发送)
maillast: 是否在轮转后发送邮件
nomail: 是否不发送邮件
其他选项:
include: 包含其他配置文件
shred/shredcycles: 是否安全删除文件(使用 shred 命令)
VectorConfig
Vector 日志收集器配置用于生成 Vector 配置文件,以便将日志发送到各种目标(Loki、Elasticsearch、S3 等):
pub struct VectorConfig {
pub enabled: bool, pub config_path: String, pub source: VectorSourceConfig, pub transforms: Vec<VectorTransformConfig>, pub sinks: Vec<VectorSinkConfig>, }
日志级别
支持的日志级别(从低到高):
"trace" - 最详细的调试信息
"debug" - 调试信息
"info" - 一般信息(推荐用于生产环境)
"warn" - 警告信息
"error" - 错误信息
只有等于或高于配置级别的日志才会被记录。例如,如果配置为 "info",则 "trace" 和 "debug" 级别的日志不会被记录。
也可以通过环境变量 RUST_LOG 来设置日志级别:
RUST_LOG=debug cargo run
API 参考
LoggingModule
日志模块,负责初始化日志系统。
pub struct LoggingModule {
_file_guard: Arc<Mutex<Option<non_blocking::WorkerGuard>>>,
}
方法
new() -> Self
创建新的 LoggingModule 实例。
init(config: Option<LoggingConfig>) -> Result<()>
初始化日志系统。
参数:
config: Option<LoggingConfig> - 日志配置,如果为 None 则使用默认配置
返回值:
Ok(()) - 初始化成功
Err(anyhow::Error) - 初始化失败
说明:
- 此方法会设置全局 tracing subscriber
- 如果全局 subscriber 已经设置(例如在测试中),会记录警告但继续执行
- 文件写入器的
WorkerGuard 会被保存,确保日志能够正确刷新
shutdown()
关闭日志系统,清理资源。
Logger
Logger 组件,用于标识日志系统已初始化。
pub struct Logger;
在实际使用中,通过 tracing 宏直接记录日志,无需通过 Logger 组件。此组件主要用于标识日志系统已初始化。
运行示例
项目提供了多个示例来演示不同的使用场景:
cargo run --example basic
cargo run --example rotation
cargo run --example path_test
cargo run --example path_test_dir
cargo run --example span_event
cargo run --example actix_web
运行示例后,可以在 ./logs/ 目录下查看生成的日志文件。
最佳实践
1. 日志级别选择
- 开发环境:使用
"debug" 或 "trace" 获取详细调试信息
- 生产环境:使用
"info" 或 "warn",避免过多日志影响性能
- 关键服务:使用
"warn",只记录警告和错误
2. 输出模式选择
- 开发环境:使用
OutputMode::Console 或 OutputMode::Both,方便查看日志
- 生产环境:使用
OutputMode::File,避免控制台输出影响性能
- 容器环境:使用
OutputMode::Both,文件用于持久化,stdout 用于容器日志收集
3. 结构化日志
充分利用结构化日志的优势:
info!(
user_id = user_id,
action = "login",
ip = %client_ip,
duration_ms = elapsed.as_millis(),
"用户登录成功"
);
info!("用户 {} 从 {} 登录,耗时 {}ms", user_id, client_ip, elapsed.as_millis());
4. 错误处理
始终处理初始化错误:
match logging_module.init(Some(config)) {
Ok(()) => {
tracing::info!("日志系统初始化成功");
}
Err(e) => {
eprintln!("日志系统初始化失败: {}", e);
std::process::exit(1);
}
}
5. 多线程环境
secra-logger 是线程安全的,可以在多线程环境中直接使用,无需额外同步:
use std::thread;
for i in 0..10 {
thread::spawn(move || {
tracing::info!(thread_id = i, "线程 {} 启动", i);
});
}
6. Request ID 注入
启用 enable_request_id 后,可以在日志中自动注入 Request ID,方便追踪请求链路。
7. 字段规范化
启用字段规范化后,日志字段会遵循 OpenTelemetry 语义约定,便于日志分析和监控系统集成。
性能考虑
- 异步写入:日志写入是异步的,不会阻塞主线程
- 批量刷新:日志会批量刷新到磁盘,提高性能
- 线程安全:使用高性能锁(
parking_lot),多线程环境下性能优秀
- JSON 序列化:使用高效的 JSON 序列化库,性能开销小
常见问题
Q: 为什么日志文件没有创建?
A: 确保日志路径的父目录存在且有写权限。如果父目录不存在,日志系统会尝试创建,但需要相应的权限。
Q: 如何更改日志级别?
A: 可以在配置中设置 level 字段,或者通过环境变量 RUST_LOG 来设置。环境变量的优先级更高。
Q: 可以在运行时更改日志级别吗?
A: 当前版本不支持运行时更改配置。需要在初始化时设置好日志级别。如果需要动态调整,可以考虑使用 tracing-subscriber 的 EnvFilter。
Q: 日志格式可以自定义吗?
A: 当前版本使用固定的 JSON 格式。如果需要自定义格式,可以修改 module.rs 中的格式化逻辑。
Q: 如何集成到现有的 tracing 系统中?
A: secra-logger 使用标准的 tracing-subscriber,可以与其他 subscriber 组合使用。但需要注意,多次调用 init 可能会失败(如果全局 subscriber 已经设置)。
Q: 如何使用 Logrotate 配置?
A: 在 LogFileConfig 中设置 logrotate 字段,配置相应的参数。然后可以使用生成的 logrotate 配置文件来管理日志文件。
安装 logrotate:如果系统上尚未安装 logrotate,请参考 Logrotate 安装指南 进行安装。支持在线安装和离线安装两种方式。
Q: 如何使用 Vector 配置?
A: 在 LoggingConfig 中设置 vector 字段,配置相应的源、转换和目标。然后可以使用生成的 Vector 配置文件来收集和转发日志。
依赖
主要依赖:
tracing - 结构化日志框架
tracing-subscriber - 订阅者实现
tracing-log - log crate 桥接
tracing-appender - 异步日志写入
parking_lot - 高性能锁实现
chrono / chrono-tz - 日期时间处理
once_cell - 全局初始化状态管理
serde / serde_json - 序列化支持
anyhow - 错误处理
thiserror - 错误类型定义
版本历史
1.0.4
- 优化依赖管理,将仅用于开发和示例的依赖移动到
dev-dependencies
- 减少生产依赖大小
1.0.3
- 优化文件滚动逻辑
- 改进错误处理
- 添加
span_event 示例
1.0.2
- 修复 let chains 语法以兼容 Rust 2021 edition
1.0.1
0.3.0
- 大幅简化代码结构
- 重构日志写入架构
- 优化文件写入性能
贡献
欢迎提交 Issue 和 Pull Request!
许可证
MIT License
Copyright (c) 2024 Secra Team
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.