Struct LoggerFormat 

pub struct LoggerFormat { /* private fields */ }

日志文件时间分割规则枚举

Implementations

impl LoggerFormat

pub fn set_file_name(self, file_name: &str) -> Self

设置固定的日志文件名

• 直接指定日志文件名，不使用文件分割规则。
• 设置后将覆盖之前通过 LoggerFormat::set_file_pattern 设置文件模式生成的文件名。
• 如果使用了 LoggerFormat::set_max_file_triggering_policy 设置日志文件大小触发策略，在文件达到指定大小时，会覆盖原日志。

参数

• self: LoggerFormat 实例
• file_name: 要设置的固定文件名

返回值

• Self: 更新文件名后的 LoggerFormat 实例

pub const fn set_bound(self, bound: u32) -> Self

设置日志消息通道的缓冲区大小

• 当通道中的日志消息数量达到边界值时，新的日志发送操作将会阻塞，直到有空间可用。

参数

• bound: 通道缓冲区容量，表示可以排队等待处理的日志消息数量

返回值

• Self: 返回修改后的配置对象，支持链式调用

性能影响

• 较小的值：减少内存使用，但在高日志量时可能导致发送阻塞
• 较大的值：提高吞吐量，但会增加内存占用和潜在的消息延迟

示例

let format = yan_log::Logger::init("logs", yan_log::LogLevel::Debug)
    .set_bound(200)  // 设置通道容量为200

注意事项

• 边界值为0时，通道变为同步通道（每次发送都会阻塞直到接收）
• 在高并发场景中建议适当增大边界值
• 边界值过大会增加内存占用和消息处理延迟

pub fn set_max_file_triggering_policy( self, max_file_triggering_policy: u64, ) -> Self

设置日志文件大小触发拆分文件策略

• 配置当日志文件达到指定大小时自动创建新文件的策略。
• 设置后会立即根据当前时间更新文件名并重置索引。

参数

• self: LoggerFormat 实例
• max_file_triggering_policy: 最大文件大小（字节），超过此大小会触发文件分割

返回值

• Self: 更新大小策略和文件名后的 LoggerFormat 实例

说明

• 值为0表示禁用文件大小分割
• 非零值表示单个日志文件的最大字节数
• 达到大小时会创建新文件，文件名中的索引会递增

示例

let mut log_fmt = yan_log::Logger::init("logs", yan_log::LogLevel::Debug);
// 1024B * 1024 = 1048576B = 1024KB = 1MB
// 1048576B * 100 = 104857600B = 100MB
let format = log_fmt.set_max_file_triggering_policy(104857600); // 设置100MB的触发策略

pub fn set_file_pattern( self, file_pattern: &str, time_division_rule: LoggerFormatTimeDivisionRule, ) -> Self

设置日志文件命名模式和时间分割规则

参数

• self: LoggerFormat 实例
• file_pattern: 文件命名模式，支持的模式占位符：
  • %Y: 四位年份
  • %m: 两位月份（01-12）
  • %d: 两位日期（01-31）
  • %H: 两位小时（00-23）
  • %M: 两位分钟（00-59）
  • %S: 两位秒数（00-59）
  • %i: 文件索引号
• time_division_rule: 明确的时间分割规则

返回值

• Self: 更新文件模式和时间分割规则后的 LoggerFormat 实例

示例

let mut log_fmt = yan_log::Logger::init("logs", yan_log::LogLevel::Debug);
let log_fmt = log_fmt.set_file_pattern("app_%Y-%m-%d.log", yan_log::LoggerFormatTimeDivisionRule::Day);

pub fn set_timezone_offset(self, offset: i128) -> Self

设置时间偏移量（单位：毫秒）

• 根据偏移量的正负值自动设置时区偏移方向
• 正数表示东时区，负数表示西时区

参数

• offset: 时间偏移量，单位为毫秒
  • 正数：东时区（UTC+）
  • 负数：西时区（UTC-）

返回值

• Self: 返回自身的所有权，支持链式调用

注意

• 内部会自动处理偏移量的正负转换，将负值转换为对应的正值并标记为负方向
• 该操作只能设置一次，后续重复设置无效

示例

let config = TimeConfig::new()
    .set_timezone_offset(28800000); // 设置为 UTC+8（8小时 = 28800000毫秒）

let config = TimeConfig::new()
    .set_timezone_offset(-18000000); // 设置为 UTC-5（-5小时 = -18000000毫秒）

pub const fn set_max_retained_files(self, max_retained_files: u64) -> Self

设置最大保留日志文件数量

参数

• self: LoggerFormat 实例
• max_retained_files: 最大保留日志文件数

返回值

• Self: 更新最大保留日志文件数后的 LoggerFormat 实例

示例

let mut log_fmt = yan_log::Logger::init("logs", yan_log::LogLevel::Debug);
let log_fmt = log_fmt.set_max_retained_files(3);

pub fn set_ignore_module(self, module: HashSet<&'static str>) -> Self

设置不记录日志的指定模块

参数

• self: LoggerFormat 实例
• module: 模块路径（例如 “my_module” 或 “my_module::sub_module”）

返回值

• Self: 更新后的配置对象，支持链式调用

示例

let log_fmt = yan_log::Logger::init("logs", yan_log::LogLevel::Debug)
    .set_ignore_module("api::v1::user")  // 忽略 api::v1::user 模块
    .start();

pub fn start(self) -> Result<(), Error>

启动日志系统

• 完成日志系统的最终配置并启动所有相关组件。
• 此方法会设置全局日志级别、注册日志实现并启动日志处理线程。

处理流程

1. 设置全局日志级别过滤
2. 注册 log crate 的日志实现
3. 启动日志发送器和处理线程

注意事项

• 此方法会消费 LoggerFormat 实例
• 调用后日志系统开始工作，可以记录日志
• 通常在应用程序启动时调用一次

示例

yan_log::Logger::init("logs", yan_log::LogLevel::Debug)
    .set_file_pattern("app_%Y-%m-%d.log", yan_log::LoggerFormatTimeDivisionRule::Day)
    .start()
    .unwrap();

安全性

• 使用 Box::leak 将日志记录器泄漏到静态生命周期，这是启动全局日志系统的常见模式

注意事项

• 默认情况，在 dev 模式会打印日志到控制台，release模式，不会打印日志到控制台
• 开启 stdout 特性时，release模式，会和 dev 模式相同打印日志到控制台