winlog

一个简单的Rust日志后端，用于将消息发送到Windows事件日志。

特性

• 使用RegisterEventSourceW和ReportEventW API将Rust日志消息写入Windows事件日志。
• 支持从RUST_LOG环境变量初始化的env_logger过滤（可选）。
• 提供实用函数，以在Windows注册表中注册/注销您的事件源。
• 在您的可执行文件中嵌入了一个小型（120字节）消息资源库，其中包含必要的日志消息模板。
• 不会引发panic。

将五个Rust日志级别映射到以下Windows事件类型

需求

• Rust 1.29+
• Windows或MinGW
• [Windows，可选] mc.exe 和 rc.exe（仅在更改eventmsgs.mc时需要）
• [Windows，可选] PowerShell（用于端到端测试）

用法

Cargo.toml

纯winlog

[dependencies]
winlog = "*"

或启用env_logger过滤支持

[dependencies]
winlog = { version = "0.2.5", features = ["env_logger"] }

在Windows中注册日志源

在Windows注册表中注册日志源

winlog::register("Example Log"); // silently ignores errors
// or
winlog::try_register("Example Log").unwrap();

这通常需要 管理员 权限，因此这通常在安装时完成。

如果你的 MSI 安装程序（或类似程序）注册了你的事件源，则不应调用此操作。

记录事件

不使用 env_logger 过滤器

winlog::init("Example Log").unwrap();

info!("Hello, Event Log");
trace!("This will be logged too");

启用 env_logger 过滤器后使用 winlog 后端

// # export RUST_LOG="info"
winlog::init("Example Log").unwrap();
info!("Hello, Event Log");
trace!("This will be filtered out");

注销日志源

注销日志源

winlog::deregister("Example Log"); // silently ignores errors
// or
winlog::try_deregister("Example Log").unwrap();

这通常在程序卸载时完成。如果你的 MSI 安装程序（或类似程序）注销了你的事件源，则不应调用此操作。

新增功能

0.2.6

• 禁用不必要的正则表达式功能以提高构建速度。
• 改进了 build.rs 中的错误报告和处理。

0.2.5

• Gitlab CI 在 Windows 10 和 Debian/MinGW 上进行构建。
• 可选支持 env_logger 事件（启用功能 env_logger）。
• 在 MinGW 上始终运行 windrc。
• 将链接器配置包含在 .cargo/config 中。

构建

Windows

cargo build --release

MinGW

安装 MinGW（Ubuntu）

sudo apt install mingw-w64

安装 Rust

rustup target install x86_64-pc-windows-gnu

目前使用 rustup 安装的 Rust 不使用正确的链接器，因此您需要将以下内容添加到 .cargo/config

[target.x86_64-pc-windows-gnu]
linker = "/usr/bin/x86_64-w64-mingw32-gcc"

构建

cargo build --release

内部

工件 eventmsgs.lib 和 eventmsgs.rs 在源代码控制之下，因此用户不需要安装 mc.exe 和 rc.exe 以进行标准构建。

1. 如果 build.rs 确定 eventmsgs.mc 已更改，则 build.rs
   • 调用 mc.exe（它创建 eventmsgs.h）
   • 调用 rc.exe（它创建 eventmsgs.lib）
   • 从 eventmsgs.h 创建 eventmsgs.rs。
2. build.rs 发出链接器标志，以便可以找到 eventmsgs.lib。
3. 标准的 cargo build 随后进行。

测试

端到端测试需要 HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application 注册表键的“完全控制”权限。

cargotest

过程

1. 创建一个唯一的临时事件源名称（winlog-test-###########）。
2. 将编译后的测试可执行文件注册为 EventMessageFile 以在 Windows 注册表中注册事件源。您可以在 HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\winlog-test-########### 中看到一个新键。
3. 向事件源写入一些日志消息。
4. 使用 PowerShell 检索已记录的消息。
5. 注销我们的事件源。这会删除 winlog-test-########## 注册表键。
6. 断言检索到的日志消息是正确的。

许可证

根据您的选择，许可协议可以是以下之一

• Apache许可证，版本2.0（LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

任选其一。

贡献

除非您明确说明，否则您有意提交给作品作为贡献的内容，如Apache-2.0许可证中定义，应按上述方式双重许可，不附加任何额外条款或条件。