etw_wrapper/lib.rs
1// On docs.rs (which sets `--cfg docsrs`) opt into the nightly `doc_cfg` feature so items gated
2// behind a Cargo feature render an "Available on crate feature ..." banner in the docs.
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![warn(missing_docs)]
5
6//! A strongly typed Event Tracing for Windows wrapper.
7//!
8//! The `gen_etw_wrapper!` macro turns an ETW manifest into a strongly typed provider struct.
9//! This crate supports Windows only.
10//!
11//! ```no_run
12//! # #[cfg(feature = "macro")]
13//! use etw_wrapper::{Result, gen_etw_wrapper};
14//!
15//! # #[cfg(feature = "macro")]
16//! gen_etw_wrapper!("manifests/widgetservice.man", PROVIDER_WIDGETSERVICE -> WidgetLogger);
17//!
18//! # #[cfg(feature = "macro")]
19//! fn main() -> Result<()> {
20//! let provider = WidgetLogger::register()?;
21//! provider.request_failed(0x12ABCDEF, 500, 42, "failed to succeed")?;
22//! Ok(())
23//! }
24//! # #[cfg(not(feature = "macro"))]
25//! # fn main() {}
26//! ```
27//!
28//! To avoid the procedural macro, call [`EtwLogger::register`], optionally check
29//! [`EtwLogger::enabled`] before [`EtwLogger::write`], and convert parameters to
30//! [`EventDataDescriptor`](field::EventDataDescriptor) instances with the helpers in the
31//! [`field`] module.
32//!
33//! ```no_run
34//! use etw_wrapper::{EtwLogger, EventDescriptor, Guid, field::*};
35//! let ctx = EtwLogger::register(&Guid::default()).unwrap();
36//! let x = 1u32;
37//! let y = to_u16cstring("hello");
38//!
39//! let descriptor = EventDescriptor::default();
40//! ctx.write(&descriptor, &[scalar(&x), str16(&y).unwrap()]).unwrap();
41//! ```
42
43#[cfg(feature = "macro")]
44#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
45pub use etw_wrapper_macro::gen_etw_wrapper;
46
47// Gives generated code a stable path when the macro is invoked from this package's own targets.
48extern crate self as etw_wrapper;
49
50// Vendored Win32 declarations generated by `cargo xtask regenerate-bindings`.
51#[allow(non_snake_case, non_camel_case_types, dead_code, clippy::all)]
52#[allow(missing_docs)]
53mod bindings;
54mod context;
55mod error;
56pub mod field;
57mod types;
58
59pub use context::EtwLogger;
60pub use error::{Error, Result};
61
62// These crate-owned types keep callers independent of any `windows` crate version.
63/// Describes an ETW event's identity and filtering metadata.
64pub use types::EventDescriptor;
65/// A Windows file time represented as 100-nanosecond intervals since January 1, 1601 UTC.
66pub use types::FileTime;
67/// A Windows globally unique identifier.
68pub use types::Guid;
69/// A Windows date and time with millisecond precision.
70pub use types::SystemTime;
71
72// `windows-bindgen` uses this referenced Win32 name in the private declarations it generates.
73#[allow(non_camel_case_types)]
74pub(crate) type EVENT_DESCRIPTOR = EventDescriptor;
75
76// Callers build payloads with `field::EventDataDescriptor`, which borrows the data it points at.
77// The raw type stays internal because its union field type is not nameable outside this crate.
78pub(crate) use types::EVENT_DATA_DESCRIPTOR;