Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
winlog
A simple Rust log backend to send messages to the Windows event log.
- Writes Rust log messages to the Windows event log using the RegisterEventSourceW and ReportEventW APIs.
- Provides utility functions to register/unregister your event source 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 as follows:
Rust Log Level | Windows Event Type | Windows Event Id |
---|---|---|
Error | Error | 1 |
Warn | Warning | 2 |
Info | Informational | 3 |
Debug | Informational | 4 |
Trace | Informational | 5 |
Requirements
- Rust 2018
- Windows
- (optional) PowerShell (used for the end-to-end test)
- (optional) mc.exe and rc.exe (only required when
eventmsgs.mc
is changed)
Usage
Add to cargo.toml
:
[dependencies]
winlog = "*"
Register the log source in the Windows registry:
winlog::register("Example Log");
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.
Use the winlog backend:
winlog::init("Example Log").unwrap();
info!("Hello, Event Log");
Deregister the log source:
winlog::deregister("Example Log");
This is usually done during program uninstall. If your MSI installer (or similar) deregisters your event sources you should not call this.
Building
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.
- If
build.rs
determines thateventmsgs.mc
was changed thenbuild.rs
:- invokes
mc.exe
(which createseventmsgs.h
) - invokes
rc.exe
(which createseventmsgs.lib
) - creates
eventmsgs.rs
fromeventmsgs.h
.
- invokes
build.rs
emits linker flags soeventmsgs.lib
can found.- 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:
- Create a unique temporary event source name (
winlog-test-###########
). - Register our compiled test executable as
EventMessageFile
for the event source in the Windows registry. You can see a new key atHKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\winlog-test-###########
. - Write some log messages to the event source.
- Use PowerShell to retrieve the logged messages.
- Deregister our event source. This removes the
winlog-test-###########
registry key. - 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.