# winlog
[](https://gitlab.com/arbitrix/winlog/pipelines)
[](https://crates.io/crates/winlog)
[](https://docs.rs/winlog)
[](https://gitlab.com/arbitrix/winlog/blob/master/LICENSE)
A simple [Rust log](https://docs.rs/log/latest/log/) backend to send messages to the [Windows event log](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-logging).
## Features
* Writes Rust log messages to the Windows event log using the
[RegisterEventSourceW](https://docs.microsoft.com/en-us/windows/desktop/api/Winbase/nf-winbase-registereventsourcew)
and [ReportEventW](https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-reporteventw) APIs.
* Supports `env_logger` filtering, initialized from RUST_LOG environment variable. (optional)
* Provides utility functions to register/unregister your
[event source](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-sources) in the Windows registry.
* Embeds a small (120-byte) message resource library containing the
necessary log message templates in your executable.
* Does not panic.
The five Rust log levels are mapped to Windows [event types](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-types) as follows:
| Error | Error | 1 |
| Warn | Warning | 2 |
| Info | Informational | 3 |
| Debug | Informational | 4 |
| Trace | Informational | 5 |
## Requirements
* Rust 1.29+
* Windows or MinGW
* [Windows, optional] [mc.exe](https://docs.microsoft.com/en-us/windows/desktop/wes/message-compiler--mc-exe-) and [rc.exe](https://docs.microsoft.com/en-us/windows/desktop/menurc/resource-compiler) (only required when `eventmsgs.mc` is changed)
* [Windows, optional] PowerShell (used for the end-to-end test)
## Usage
### Cargo.toml
Plain winlog:
```
[dependencies]
winlog = "*"
```
Or to enable env_logger filtering support:
```
[dependencies]
winlog = { version = "0.2.5", features = ["env_logger"] }
```
### Register log source with Windows
Register the log source in the Windows registry:
```
winlog::register("Example Log"); // silently ignores errors
// or
winlog::try_register("Example Log").unwrap();
```
This usually requires `Administrator` permission so this is usually done during
installation time.
If your MSI installer (or similar) registers your event sources you should not call this.
### Log events
Without env_logger filtering:
```
winlog::init("Example Log").unwrap();
info!("Hello, Event Log");
trace!("This will be logged too");
```
Use the winlog backend with env_logger filter enabled:
```
// # export RUST_LOG="info"
winlog::init("Example Log").unwrap();
info!("Hello, Event Log");
trace!("This will be filtered out");
```
### Deregister log source
Deregister the log source:
```
winlog::deregister("Example Log"); // silently ignores errors
// or
winlog::try_deregister("Example Log").unwrap();
```
This is usually done during program uninstall. If your MSI
installer (or similar) deregisters your event sources you should not call this.
## What's New
### 0.2.6
* Disable unneeded regex features to speed up the build.
* Improve error reporting/handling in `build.rs`.
### 0.2.5
* Gitlab CI builds on Windows 10 and Debian/MinGW.
* Optional support for env_logger event (enable feature `env_logger`).
* Always run `windrc/windrc` on MinGW.
* Include linker configuration in `.cargo/config`.
## Building
### Windows
```sh
cargo build --release
```
### MinGW
Install MinGW (Ubuntu):
```sh
sudo apt install mingw-w64
```
Install Rust:
```sh
rustup target install x86_64-pc-windows-gnu
```
Currently the install from rustup doesn't use the correct linker so you have to add the following to `.cargo/config`:
[target.x86_64-pc-windows-gnu]
linker = "/usr/bin/x86_64-w64-mingw32-gcc"
Build:
```sh
cargo build --release
```
### Internals
Artifacts `eventmsgs.lib` and `eventmsgs.rs` are under source control so users
don't need to have `mc.exe` and `rc.exe` installed for a standard build.
1. If `build.rs` determines that `eventmsgs.mc` was changed then `build.rs`:
* invokes `mc.exe` (which creates `eventmsgs.h`)
* invokes `rc.exe` (which creates `eventmsgs.lib`)
* creates `eventmsgs.rs` from `eventmsgs.h`.
2. `build.rs` emits linker flags so `eventmsgs.lib` can found.
3. Standard `cargo build` follows.
## Testing
The end-to-end test requires 'Full Control' permissions on the
`HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application`
registry key.
```cargo test```
Process:
1. Create a unique temporary event source name (`winlog-test-###########`).
2. Register our compiled test executable as ```EventMessageFile``` for
the event source in the Windows registry. You can see a new key at
`HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\winlog-test-###########`.
2. Write some log messages to the event source.
3. Use PowerShell to retrieve the logged messages.
4. Deregister our event source. This removes the `winlog-test-###########`
registry key.
5. Assert that the retrieved log messages are correct.
## License
Licensed under either of
* Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.